Merge fix/486: fail the apply when the deployment artifact could not be read

Claude-Session: https://claude.ai/code/session_01GASWkNEi68FSCtvr6rLoEW
docs(486): live-gate the failed-apply fix on docker-dev
2026-07-21 03:27:58 -04:00 · 2026-07-21 03:27:54 -04:00 · 2026-07-21 03:22:40 -04:00 · 2026-07-21 03:02:07 -04:00 · 2026-07-21 03:02:02 -04:00 · 2026-07-21 02:40:18 -04:00
344 changed files with 34723 additions and 8501 deletions
@@ -68,9 +68,45 @@ shared-lib consumption, or per-project commands — update the **OtOpcUa entry i
   gRPC session. The gateway owns the COM apartment + STA pump
   server-side; the driver speaks `MxCommand` / `MxEvent` protos
   exclusively.
-3. **OPC UA Server** — Exposes authored equipment tags as variable nodes.
-   Galaxy tags are bound by `TagConfig.FullName` (`tag_name.AttributeName`);
-   reads/writes/subscriptions are translated to that reference for MXAccess.
+3. **OPC UA Server** — Exposes the deployed tree under **two OPC UA namespaces**
+   (see below). Galaxy tags are bound by `TagConfig.FullName`
+   (`tag_name.AttributeName`); reads/writes/subscriptions are translated to that
+   reference for MXAccess.
+
+### v3 OPC UA Address Space (Batch 4): dual namespace
+
+The server exposes **two OPC UA namespaces** (replacing the single
+`https://zb.com/otopcua/ns`), built by `AddressSpaceComposer` /
+`AddressSpaceApplier` and served by `OtOpcUaNodeManager` (which registers both
+URIs; `V3NodeIds` + `AddressSpaceRealm` are the identity authority):
+
+| Namespace URI | Realm | Subtree | NodeId `s=` scheme |
+|---|---|---|---|
+| `https://zb.com/otopcua/raw` | `AddressSpaceRealm.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` | `AddressSpaceRealm.Uns` | the UNS tree (Area → Line → Equipment → signal) | slash-joined **`Area/Line/Equipment/EffectiveName`** |
+
+- **Single source, fanned to both.** Every device value has exactly one source —
+  the raw tag's node. A `UnsTagReference` projects that raw tag into an equipment
+  as a UNS-namespace variable that carries an **`Organizes` reference to its raw
+  node** and mirrors it. One driver publish for a RawPath fans (in `DriverHostActor`)
+  to the raw NodeId AND every referencing UNS NodeId with identical
+  value/quality/timestamp — the mux key stays single (RawPath).
+- **Writes via either NodeId** route to the same driver ref under the same
+  `WriteOperate` gating (the node-manager write gate is realm-qualified and fails
+  closed); a failed device write reverts both NodeIds via the shared fan-out
+  (write-outcome self-correction).
+- **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 — one `ReportEvent`, one Server-object copy; ack/confirm/shelve route on
+  `ConditionId = RawPath`.
+- **Historian dual-registration.** Both NodeIds register the **same** historian
+  tagname; the mux `HistorizedTagRef` stays single (RawPath). HistoryRead works
+  through either NodeId.
+
+The retired `EquipmentNodeIds` (`{equipmentId}/{folderPath}/{name}`) scheme and
+the single-namespace `EquipmentTags` materialization path are gone. See
+`docs/plans/2026-07-15-raw-uns-two-subtree-v3-design.md` +
+`docs/plans/2026-07-15-v3-batch4-address-space-plan.md`, and `docs/Uns.md`.

 ### Key Concept: Tag Name and FullName

@@ -183,6 +219,24 @@ The server supports configurable OPC UA transport security via the `OpcUa:Enable

 The server supports non-transparent warm/hot redundancy via the `Redundancy` section in `appsettings.json`. Two instances share the same Galaxy DB and the same mxaccessgw (under distinct `MxAccess.ClientName` values) but have unique `ApplicationUri` values. Each exposes `RedundancySupport`, `ServerUriArray`, and a dynamic `ServiceLevel` based on role and runtime health. The primary advertises a higher ServiceLevel than the secondary. See `docs/Redundancy.md` for the full guide.

+## LocalDb pair-local config cache (Phase 1)
+
+Every **driver-role** node keeps a consolidated `ZB.MOM.WW.LocalDb` SQLite database (the retired
+LiteDB `LocalCache` subsystem was deleted as superseded). Phase-1 scope: it caches the
+**deployed-configuration artifact** (chunked, SHA-256-verified, newest-2 retention per cluster) so a
+driver node can **boot from cache when central SQL Server is unreachable** — `DriverHostActor` writes
+the cache after each successful apply (`IDeploymentArtifactCache` → `LocalDbDeploymentArtifactCache`,
+in `Runtime/Deployment/`) and reads it as a boot fallback, flagging running-from-cache. Wired by
+`AddOtOpcUaLocalDb` in the `hasDriver` branch only (`Host/Configuration/LocalDbRegistration.cs` +
+`LocalDbSetup.OnReady`, whose DDL→`RegisterReplicated` order is load-bearing); **admin-only nodes
+never register it.** The cache can optionally replicate to the node's redundant pair peer over the
+library's gRPC sync — **default-OFF, fail-closed bearer auth** (`LocalDbSyncAuthInterceptor`), gated
+on `LocalDb:SyncListenPort` (a dedicated Kestrel h2c listener) + `LocalDb:Replication:*`. On the
+docker-dev rig the **site-a pair** has replication on; central + site-b stay default-OFF (site-b is
+the pin). ApiKey via `${secret:}`/env, never committed (the rig's dev key is the committed-dev-secret
+exception). See `docs/Configuration.md` (`LocalDb` section), `docs/Redundancy.md` (pair-local config
+cache), and the runbook `docs/operations/2026-07-20-localdb-pair-replication.md`.
+
 ## LDAP Authentication

 The server uses LDAP-based user authentication via the `Security:Ldap` section in `appsettings.json`. When enabled, credentials are validated by LDAP bind against a GLAuth server, and LDAP group membership maps to OPC UA permissions: `ReadOnly` (browse/read), `WriteOperate` (write FreeAccess/Operate attributes), `WriteTune` (write Tune attributes), `WriteConfigure` (write Configure attributes), `AlarmAck` (alarm acknowledgment). `LdapOpcUaUserAuthenticator` (`src/Server/ZB.MOM.WW.OtOpcUa.Host/OpcUa/LdapOpcUaUserAuthenticator.cs`) implements `IOpcUaUserAuthenticator`, delegating the LDAP bind + group lookup to `OtOpcUaLdapAuthService` (`src/Server/ZB.MOM.WW.OtOpcUa.Security/Ldap/OtOpcUaLdapAuthService.cs`, an `ILdapAuthService`). See `docs/security.md` for the full guide.
@@ -215,6 +269,12 @@ Address pickers in AdminUI support live browse for OpcUaClient and Galaxy driver

 The AdminUI's global **UNS** page (`/uns`) is the single surface for managing the unified namespace fleet-wide (Area → Line → Equipment → Tag/VirtualTag), replacing the old per-cluster UNS/Equipment/Tags tabs. See `docs/Uns.md`.

+**v3 (Batch 2): device I/O is authored in the `/raw` project tree** (`GlobalRaw.razor` → `RawTree.razor`, `IRawTreeService`) — a cluster-rooted `Folder → Driver → Device → TagGroup → Tag` hierarchy with per-node context menus (the reusable `ContextMenu`), lazy loading, driver/device config modals (endpoint moved to `Device.DeviceConfig`; Test-connect probes the `DriverDeviceConfigMerger`-merged config), manual-entry + CSV import/export (RFC-4180, staged review grid, all-or-nothing), and browse-commit of discovered leaves into raw tags. The routed `/clusters/{id}/drivers` flow (`DriverTypePicker`, `DriverEditRouter`, the 8 `*DriverPage` shells, the Drivers list) is **retired** — its form bodies live on inside the `/raw` modals. The `DriverType` dispatch maps are keyed off the `DriverTypeNames` constants (fixing the `TwinCat`/`Focas` drift). A `Calculation` pseudo-driver (`DriverTypeNames.Calculation`, `IDependencyConsumer`, deploy-time `scriptId`-existence + Tarjan cycle gates) computes signal-level tags from other tags' RawPaths. See `docs/Raw.md`.
+
+**v3 (Batch 3): UNS Equipment is reference-only.** The equipment **Tags** tab no longer authors or binds tags — it holds `UnsTagReference` rows pointing at raw tags authored in `/raw`. "+ Add reference" opens the `RawTree` in picker mode, **cluster-scoped** (structurally + server-enforced `tag.cluster == equipment.cluster`); rows show effective name / RawPath / inherited DataType+AccessLevel / display-name override. **Effective-name uniqueness** (references + VirtualTags + ScriptedAlarms share the `{EquipmentId}/{EffectiveName}` NodeId space) is enforced at authoring (`IEffectiveNameGuard`) and at the deploy gate (`DraftValidator.UnsEffectiveNameCollision` — catches rename-induced collisions). Scripts use **`ctx.GetTag("{{equip}}/<RefName>")`** — resolved per-equipment through `UnsTagReference` effective names to the backing RawPath at both compose seams (`AddressSpaceComposer` + `DeploymentArtifact`, via the shared `EquipmentReferenceMap`, byte-parity); an unresolved `<RefName>` is a deploy error (`EquipReferenceUnresolved`) AND a live Monaco diagnostic (`OTSCRIPT_EQUIPREF`) — editor accepts ⇔ publish accepts. `EquipmentScriptPaths.DeriveEquipmentBase` is deleted (the dot-joint `{{equip}}.X` became the slash-joint `{{equip}}/<RefName>`). Raw rename warns when a beneath-it tag is historized-without-override / UNS-referenced / named by a script literal (`RawTreeService` substring scan). `ImportEquipmentModal` dropped the `DriverInstanceId` column. See `docs/Uns.md` + `docs/ScriptEditor.md`.
+
+**v3 (Batch 4 = v3.0): dual-namespace address space.** The OPC UA server exposes **two namespaces** — `https://zb.com/otopcua/raw` (Raw device tree, `s=<RawPath>`) + `https://zb.com/otopcua/uns` (UNS tree, `s=<Area>/<Line>/<Equipment>/<EffectiveName>`) — replacing the single `.../ns` and the retired `EquipmentNodeIds` scheme. Every value has ONE source (the raw node's publish); a driver publish for a RawPath fans in `DriverHostActor` to the raw NodeId AND every referencing UNS NodeId with identical value/quality/timestamp, and each UNS variable `Organizes`-references its raw node. Writes route via **either** NodeId to the same driver ref under the same realm-qualified `WriteOperate` gate (failed-write revert works through both); native alarms materialize ONCE at the raw tag (`ConditionId = RawPath`) and fan via SDK `AddNotifier` to the raw device folder + every referencing equipment folder (one `ReportEvent`, one Server-object copy); both NodeIds register the SAME historian tagname (mux `HistorizedTagRef` stays single, keyed by RawPath). Identity authority: `V3NodeIds` + `AddressSpaceRealm` (carried explicitly at every sink seam — never parsed out of the id string). See the "v3 OPC UA Address Space (Batch 4)" section above, `docs/Uns.md`, and `docs/plans/2026-07-15-v3-batch4-address-space-plan.md`.
+
 The `/uns` **TagModal** uses **driver-typed tag-config editors**: it dispatches by the bound driver's `DriverType` to a per-driver editor (Modbus/S7/AbCip/AbLegacy/TwinCAT/Focas/OpcUaClient) via `TagConfigEditorMap`, with client-side validation via `TagConfigValidator`; unmapped drivers (only Galaxy) fall back to the generic raw-`TagConfig`-JSON textarea. Each editor is a thin razor shell over a pure `<Driver>TagConfigModel` (`FromJson`/`ToJson`/`Validate`, preserves unknown keys). To add a driver's editor, copy the Modbus template under `Components/Shared/Uns/TagEditors/` + `Uns/TagEditors/`, reusing the driver's enums + camelCase JSON property names, and register it in `TagConfigEditorMap` + `TagConfigValidator`. See `docs/plans/2026-06-09-driver-typed-tag-editors-design.md`.

 ## Scripting / Script Editor
@@ -29,10 +29,10 @@
    <PackageVersion Include="coverlet.collector" Version="6.0.4" />
    <PackageVersion Include="FluentAssertions" Version="8.3.0" />
    <PackageVersion Include="Google.Protobuf" Version="3.34.1" />
+    <PackageVersion Include="Grpc.AspNetCore" Version="2.76.0" />
    <PackageVersion Include="Grpc.Core.Api" Version="2.76.0" />
    <PackageVersion Include="Grpc.Net.Client" Version="2.76.0" />
    <PackageVersion Include="libplctag" Version="1.5.2" />
-    <PackageVersion Include="LiteDB" Version="5.0.21" />
    <PackageVersion Include="MessagePack" Version="2.5.301" />
    <PackageVersion Include="Microsoft.AspNetCore.Authorization" Version="10.0.7" />
    <PackageVersion Include="Microsoft.AspNetCore.DataProtection" Version="10.0.7" />
@@ -122,6 +122,13 @@
    <PackageVersion Include="xunit.runner.visualstudio" Version="3.0.2" />
    <PackageVersion Include="xunit.v3" Version="1.1.0" />
    <PackageVersion Include="ZB.MOM.WW.Health" Version="0.1.0" />
+    <!--
+      LocalDb: embedded SQLite node-local cache + optional 2-node gRPC replication. The core
+      package floors the native SQLitePCLRaw.lib.e_sqlite3 at 2.1.12, so consumers inherit the
+      CVE-2025-6965-fixed native binary without needing the surgical pin below.
+    -->
+    <PackageVersion Include="ZB.MOM.WW.LocalDb" Version="0.1.3" />
+    <PackageVersion Include="ZB.MOM.WW.LocalDb.Replication" Version="0.1.3" />
    <PackageVersion Include="ZB.MOM.WW.Health.Akka" Version="0.1.0" />
    <PackageVersion Include="ZB.MOM.WW.Health.EntityFrameworkCore" Version="0.1.0" />
    <PackageVersion Include="ZB.MOM.WW.Telemetry" Version="0.1.0" />
@@ -129,9 +136,13 @@
    <PackageVersion Include="ZB.MOM.WW.MxGateway.Client" Version="0.1.1" />
    <PackageVersion Include="ZB.MOM.WW.MxGateway.Contracts" Version="0.1.1" />
    <PackageVersion Include="ZB.MOM.WW.Configuration" Version="0.1.0" />
-    <PackageVersion Include="ZB.MOM.WW.Auth.Abstractions" Version="0.1.1" />
-    <PackageVersion Include="ZB.MOM.WW.Auth.Ldap" Version="0.1.1" />
-    <PackageVersion Include="ZB.MOM.WW.Auth.AspNetCore" Version="0.1.1" />
+    <PackageVersion Include="ZB.MOM.WW.Auth.Abstractions" Version="0.1.5" />
+    <PackageVersion Include="ZB.MOM.WW.Auth.Ldap" Version="0.1.5" />
+    <PackageVersion Include="ZB.MOM.WW.Auth.AspNetCore" Version="0.1.5" />
+    <PackageVersion Include="ZB.MOM.WW.Secrets" Version="0.2.3" />
+    <PackageVersion Include="ZB.MOM.WW.Secrets.Abstractions" Version="0.2.3" />
+    <PackageVersion Include="ZB.MOM.WW.Secrets.Ui" Version="0.2.3" />
+    <PackageVersion Include="ZB.MOM.WW.Secrets.Replicator.AkkaDotNet" Version="0.2.3" />
    <PackageVersion Include="ZB.MOM.WW.Audit" Version="0.1.0" />
    <PackageVersion Include="ZB.MOM.WW.Theme" Version="0.3.1" />
    <PackageVersion Include="ZB.MOM.WW.HistorianGateway.Client" Version="0.3.0" />
@@ -25,6 +25,10 @@
      <package pattern="ZB.MOM.WW.Theme" />
      <package pattern="ZB.MOM.WW.HistorianGateway.Contracts" />
      <package pattern="ZB.MOM.WW.HistorianGateway.Client" />
+      <package pattern="ZB.MOM.WW.Secrets" />
+      <package pattern="ZB.MOM.WW.Secrets.*" />
+      <package pattern="ZB.MOM.WW.LocalDb" />
+      <package pattern="ZB.MOM.WW.LocalDb.*" />
    </packageSource>
  </packageSourceMapping>
 </configuration>
@@ -21,6 +21,7 @@
    <Project Path="src/Server/ZB.MOM.WW.OtOpcUa.Security/ZB.MOM.WW.OtOpcUa.Security.csproj" />
  </Folder>
  <Folder Name="/src/Drivers/">
+    <Project Path="src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Calculation/ZB.MOM.WW.OtOpcUa.Driver.Calculation.csproj" />
    <Project Path="src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Galaxy/ZB.MOM.WW.OtOpcUa.Driver.Galaxy.csproj" />
    <Project Path="src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Browser/ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Browser.csproj" />
    <Project Path="src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Contracts/ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Contracts.csproj" />
@@ -81,6 +82,7 @@
    <Project Path="tests/Server/ZB.MOM.WW.OtOpcUa.Security.Tests/ZB.MOM.WW.OtOpcUa.Security.Tests.csproj" />
  </Folder>
  <Folder Name="/tests/Drivers/">
+    <Project Path="tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Calculation.Tests/ZB.MOM.WW.OtOpcUa.Driver.Calculation.Tests.csproj" />
    <Project Path="tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Tests/ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Tests.csproj" />
    <Project Path="tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Browser.Tests/ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Browser.Tests.csproj" />
    <Project Path="tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.Gateway.Tests/ZB.MOM.WW.OtOpcUa.Driver.Historian.Gateway.Tests.csproj" />
@@ -47,6 +47,29 @@

 name: otopcua-dev

+# ── Shared secret-replication env (all six host nodes) ──────────────────────────
+# Akka peer-to-peer clustered secret replication rides the existing `otopcua` Akka
+# mesh (DistributedPubSub topic `zb-mom-ww-secrets`) across all six host nodes. Two
+# hard requirements are wired here, identically, on every node:
+#   1. Secrets__Replication__Enabled=true  → SecretsRegistration.AddOtOpcUaSecrets
+#      switches from plain AddZbSecrets to AddZbSecretsAkkaReplication + the eager
+#      SecretReplicationStarter hosted service, so every node joins anti-entropy.
+#   2. ZB_SECRETS_MASTER_KEY  → the ONE shared 32-byte base64 KEK. Every node MUST
+#      carry the SAME key or peers fail closed decrypting each other's rows
+#      (kek_id mismatch). appsettings.json binds Secrets:MasterKey:Source=Environment
+#      / EnvVarName=ZB_SECRETS_MASTER_KEY, so this env var IS the KEK on every node.
+# The KEK below is a committed DEV-ONLY default (matches the rig's zero-operator-step
+# philosophy, like the committed dev SQL password). Override for a fresh key with:
+#   OTOPCUA_SECRETS_KEK=$(openssl rand -base64 32) docker compose ... up -d
+# NEVER reuse this key outside this local dev rig.
+# AnnounceInterval is shortened to 5s (default 30s) so anti-entropy convergence is
+# observable quickly during dev exercise. Each node keeps its own local SQLite store
+# (Secrets:SqlitePath=otopcua-secrets.db, per-container); replication syncs them.
+x-secrets-env: &secrets-env
+  Secrets__Replication__Enabled: "true"
+  Secrets__Replication__AnnounceInterval: "00:00:05"
+  ZB_SECRETS_MASTER_KEY: "${OTOPCUA_SECRETS_KEK:-ZYGhIX0luS/XsevpCB2W18jYHMcqO6AjM9oXy+T6Zp4=}"
+
 services:

  sql:
@@ -145,6 +168,7 @@ services:
      sql: { condition: service_healthy }
      migrator: { condition: service_completed_successfully }
    environment:
+      <<: *secrets-env
      OTOPCUA_ROLES: "admin,driver"
      ASPNETCORE_URLS: "http://+:9000"
      ConnectionStrings__ConfigDb: "Server=sql,1433;Database=OtOpcUa;User Id=sa;Password=OtOpcUa!Dev123;TrustServerCertificate=True;"
@@ -200,8 +224,15 @@ services:
      Serilog__MinimumLevel__Override__Microsoft.EntityFrameworkCore: "Warning"
      Serilog__MinimumLevel__Override__Microsoft.AspNetCore: "Warning"
      GALAXY_MXGW_API_KEY: "${GALAXY_MXGW_API_KEY:-mxgw_otopcua2_GI7-tNozYE6cXGUSgEzL3AHDV7bYcYIHdMwKYgyHdX4}"
+      # Consolidated pair-local config cache (ZB.MOM.WW.LocalDb). Every driver-role node
+      # (central is admin,driver) gets one, on a per-node named volume so the cache survives
+      # container recreates. The central pair leaves replication OFF (default) — only the
+      # site-a pair replicates, as the enablement demo; site-b is the default-OFF pin.
+      LocalDb__Path: "/app/data/otopcua-localdb.db"
    ports:
      - "4840:4840"
+    volumes:
+      - otopcua-localdb-central-1:/app/data

  central-2:
    <<: *otopcua-host
@@ -210,6 +241,7 @@ services:
      central-1: { condition: service_started }
      migrator: { condition: service_completed_successfully }
    environment:
+      <<: *secrets-env
      OTOPCUA_ROLES: "admin,driver"
      ASPNETCORE_URLS: "http://+:9000"
      ConnectionStrings__ConfigDb: "Server=sql,1433;Database=OtOpcUa;User Id=sa;Password=OtOpcUa!Dev123;TrustServerCertificate=True;"
@@ -258,8 +290,12 @@ services:
      Serilog__MinimumLevel__Override__Microsoft.EntityFrameworkCore: "Warning"
      Serilog__MinimumLevel__Override__Microsoft.AspNetCore: "Warning"
      GALAXY_MXGW_API_KEY: "${GALAXY_MXGW_API_KEY:-mxgw_otopcua2_GI7-tNozYE6cXGUSgEzL3AHDV7bYcYIHdMwKYgyHdX4}"
+      # Pair-local config cache; central pair leaves replication OFF (see central-1).
+      LocalDb__Path: "/app/data/otopcua-localdb.db"
    ports:
      - "4841:4840"
+    volumes:
+      - otopcua-localdb-central-2:/app/data

  # ── Site A cluster (2-node driver-only) ─────────────────────────────────────
  # Driver-only members of the single mesh, scoped to SITE-A by ClusterId. No UI,
@@ -280,6 +316,7 @@ services:
      Cluster__PublicHostname: "site-a-1"
      Cluster__SeedNodes__0: "akka.tcp://otopcua@central-1:4053"
      Cluster__Roles__0: "driver"
+      <<: *secrets-env
      # Quiet EF/AspNetCore SQL flood — see central-1 (Serilog override). mem_limit/
      # mem_reservation are inherited from the *otopcua-host anchor.
      Serilog__MinimumLevel__Override__Microsoft.EntityFrameworkCore: "Warning"
@@ -287,8 +324,24 @@ services:
      # Resolved at runtime by GalaxyDriver.ResolveApiKey when a DriverInstance's
      # Gateway.ApiKeySecretRef = "env:GALAXY_MXGW_API_KEY".
      GALAXY_MXGW_API_KEY: "${GALAXY_MXGW_API_KEY:-mxgw_otopcua2_GI7-tNozYE6cXGUSgEzL3AHDV7bYcYIHdMwKYgyHdX4}"
+      # Pair-local config cache + REPLICATION ON — the site-a pair is the enablement demo.
+      # site-a-1 is the initiator: it binds the h2c sync listener on 9001 AND dials the peer.
+      # Setting SyncListenPort makes Program.cs add a dedicated Http2-only Kestrel listener and
+      # re-bind the primary HTTP port (an explicit Listen* otherwise discards ASPNETCORE_URLS).
+      LocalDb__Path: "/app/data/otopcua-localdb.db"
+      LocalDb__SyncListenPort: "9001"
+      LocalDb__Replication__PeerAddress: "http://site-a-2:9001"
+      # DEV-ONLY committed key (rig philosophy — like the SQL password + secrets KEK above). It
+      # MUST be byte-identical on both nodes: the interceptor is fail-closed, so any mismatch
+      # silently stops the pair converging. NEVER reuse this key outside this local dev rig.
+      LocalDb__Replication__ApiKey: "dev-site-a-localdb-sync-key"
+      # Row-count batching against gRPC's 4 MB message cap; artifact chunk rows are ≈171 KB, so
+      # 16 × 171 KB ≈ 2.7 MB stays under the cap with headroom.
+      LocalDb__Replication__MaxBatchSize: "16"
    ports:
      - "4842:4840"
+    volumes:
+      - otopcua-localdb-site-a-1:/app/data

  site-a-2:
    <<: *otopcua-host
@@ -304,11 +357,22 @@ services:
      Cluster__PublicHostname: "site-a-2"
      Cluster__SeedNodes__0: "akka.tcp://otopcua@central-1:4053"
      Cluster__Roles__0: "driver"
+      <<: *secrets-env
      Serilog__MinimumLevel__Override__Microsoft.EntityFrameworkCore: "Warning"
      Serilog__MinimumLevel__Override__Microsoft.AspNetCore: "Warning"
      GALAXY_MXGW_API_KEY: "${GALAXY_MXGW_API_KEY:-mxgw_otopcua2_GI7-tNozYE6cXGUSgEzL3AHDV7bYcYIHdMwKYgyHdX4}"
+      # site-a-2 is the passive half of the replicating pair: it binds the sync listener on 9001
+      # but does NOT dial (no PeerAddress). The replication stream is bidirectional, so a-1's
+      # single dial carries both directions. Same key + MaxBatchSize as a-1 (byte-identical key
+      # is mandatory — the interceptor fail-closes on a mismatch).
+      LocalDb__Path: "/app/data/otopcua-localdb.db"
+      LocalDb__SyncListenPort: "9001"
+      LocalDb__Replication__ApiKey: "dev-site-a-localdb-sync-key"
+      LocalDb__Replication__MaxBatchSize: "16"
    ports:
      - "4843:4840"
+    volumes:
+      - otopcua-localdb-site-a-2:/app/data

  # ── Site B cluster (2-node driver-only) ─────────────────────────────────────

@@ -326,11 +390,18 @@ services:
      Cluster__PublicHostname: "site-b-1"
      Cluster__SeedNodes__0: "akka.tcp://otopcua@central-1:4053"
      Cluster__Roles__0: "driver"
+      <<: *secrets-env
      Serilog__MinimumLevel__Override__Microsoft.EntityFrameworkCore: "Warning"
      Serilog__MinimumLevel__Override__Microsoft.AspNetCore: "Warning"
      GALAXY_MXGW_API_KEY: "${GALAXY_MXGW_API_KEY:-mxgw_otopcua2_GI7-tNozYE6cXGUSgEzL3AHDV7bYcYIHdMwKYgyHdX4}"
+      # site-b is the default-OFF pin: it gets the pair-local cache but NO SyncListenPort and NO
+      # replication config, so no sync listener binds and ISyncStatus stays disconnected/Healthy.
+      # This is what the live gate's check 8 verifies — the cache works locally with replication off.
+      LocalDb__Path: "/app/data/otopcua-localdb.db"
    ports:
      - "4844:4840"
+    volumes:
+      - otopcua-localdb-site-b-1:/app/data

  site-b-2:
    <<: *otopcua-host
@@ -346,11 +417,16 @@ services:
      Cluster__PublicHostname: "site-b-2"
      Cluster__SeedNodes__0: "akka.tcp://otopcua@central-1:4053"
      Cluster__Roles__0: "driver"
+      <<: *secrets-env
      Serilog__MinimumLevel__Override__Microsoft.EntityFrameworkCore: "Warning"
      Serilog__MinimumLevel__Override__Microsoft.AspNetCore: "Warning"
      GALAXY_MXGW_API_KEY: "${GALAXY_MXGW_API_KEY:-mxgw_otopcua2_GI7-tNozYE6cXGUSgEzL3AHDV7bYcYIHdMwKYgyHdX4}"
+      # site-b default-OFF pin (see site-b-1): cache on, replication off.
+      LocalDb__Path: "/app/data/otopcua-localdb.db"
    ports:
      - "4845:4840"
+    volumes:
+      - otopcua-localdb-site-b-2:/app/data

  traefik:
    image: traefik:v3.1
@@ -371,3 +447,13 @@ services:
 volumes:
  # SQL Server data dir — persists the OtOpcUa ConfigDb across container recreates.
  otopcua-mssql-data:
+  # Per-node pair-local config-cache (ZB.MOM.WW.LocalDb) files. One volume per node — the
+  # cache is node-local, not shared; it persists the cached deployment artifact (and, on the
+  # site-a pair, the replicated oplog state) across container recreates so a node can boot
+  # from cache after a restart even with central SQL down.
+  otopcua-localdb-central-1:
+  otopcua-localdb-central-2:
+  otopcua-localdb-site-a-1:
+  otopcua-localdb-site-a-2:
+  otopcua-localdb-site-b-1:
+  otopcua-localdb-site-b-2:
@@ -24,6 +24,163 @@ condition — the dedup logic prefers the richer driver-native record
 because it carries the full operator + raise-time + category metadata
 that the value-driven path collapses.

+## v3 Batch 4 — multi-notifier delivery (raw + equipment folders)
+
+Under the v3 dual-namespace address space, a native driver alarm is authored on a
+**raw tag** (`/raw`) and its Part 9 `AlarmConditionState` materializes **once** at the
+raw tag — `ConditionId` = the tag's **RawPath**, parent notifier = the raw device/group
+folder (`ns=Raw`). Because equipment references raw tags (v3 reference-only UNS), the
+same condition is wired as an **event notifier of every referencing equipment folder**
+(`ns=UNS`) via the SDK `AddNotifier` pattern (`OtOpcUaNodeManager.WireAlarmNotifiers`):
+`alarm.AddNotifier(equipFolder, isInverse:true)` + `equipFolder.AddNotifier(alarm)` +
+`EnsureFolderIsEventNotifier(equipFolder)`.
+
+- A **single** `ReportEvent` fans through the SDK notifier graph to the raw device folder,
+  every referencing equipment folder, and up to the Server object. A subscriber at any one
+  root receives **exactly one** copy of the transition — the Part 9 shared-`InstanceStateSnapshot`
+  dedup (`MonitoredItem.QueueEvent` → `IsEventContainedInQueue`), **never** one copy per root.
+  Duplicating the `ReportEvent` per root is rejected by design (distinct EventIds would break
+  Server-object dedup + Part 9 ack correlation).
+- **Teardown is symmetric:** the node manager tracks the wired notifier pairs and calls
+  `RemoveNotifier(..., bidirectional:true)` on rebuild / subtree-removal / reference-removal, so
+  inverse-notifier entries never leak across redeploys.
+- **Ack/confirm/shelve route on `ConditionId = RawPath`** (never `SourceNodeId`) regardless of
+  which notifier root the operator subscribed at — an ack issued from an equipment-folder
+  subscription resolves to the same raw condition.
+- The `alerts`-topic `AlarmTransitionEvent` carries the (possibly empty) **list of referencing
+  equipment paths**, and the AdminUI `/alerts` page shows **one row per condition** (primary
+  identity RawPath + condition NodeId) with the equipment list as display metadata.
+
+## Condition event identity fields (what a client reads on the wire)
+
+Every condition event — native and scripted — carries the mandatory `BaseEventType` identity
+fields, assigned at materialize time in `OtOpcUaNodeManager.MaterialiseAlarmCondition`. The SDK
+does **not** synthesize them on this path (`Create` builds the children from the type definition
+but leaves them unset; `ReportEvent` / `InstanceStateSnapshot` copy children verbatim), so they
+are set explicitly. Leaving them unset shipped them as **null** on every event — see issues #473
+(the `BaseEventType` trio) and #475 (the `ConditionType` classification pair).
+
+| Field | Value | Notes |
+|---|---|---|
+| `EventType` | the **concrete** materialized type (`TypeDefinitionId`) | e.g. `OffNormalAlarmType`; falls back to `AlarmConditionType` for an unknown authored type. Readable as a *field*, not only via an `OfType` where-clause |
+| `SourceNode` | the condition's **own NodeId** — equal to `ConditionId` | The condition **is** the source: an alarm-bearing raw tag materializes only the condition, with no sibling value variable, so there is no other node to point at |
+| `SourceName` | the same identifying id string: **RawPath** (native) / **ScriptedAlarmId** (scripted) | Deliberately the *unique* id, **not** the leaf name |
+| `ConditionName` | the leaf / display name (e.g. `HR200`) | Where the short human-readable name lives |
+| `ConditionClassId` | always **`BaseConditionClassType`** | Part 9's "no condition class modelled" value. Unset shipped `NodeId.Null` (#475) |
+| `ConditionClassName` | always **`"BaseConditionClass"`** | Matches `ConditionClassId`. Unset shipped empty text (#475) |
+| `Quality` | the condition's **source-data quality** — native tracks the source's connectivity (`Good` / `Bad`); scripted takes the worst of its input tags' qualities (#478) | A pure annotation; never alters Active/Acked/Retain. Unset shipped the accidentally-Good default (#477) — see below |
+
+**Why `BaseConditionClassType` and not `ProcessConditionClassType`.** We hold no per-alarm
+classification at the materialize seam, and `ConditionClassId` is a wire contract clients bucket on.
+`BaseConditionClassType` is the honest, spec-conformant report of *"this server does not model
+condition classes"* — it fixes the real defect (a null that breaks conformant clients) without
+asserting a classification we cannot back. `ProcessConditionClassType` — the SDK sample's pick —
+was rejected deliberately: it would be *actively wrong* for a Galaxy alarm whose upstream category is
+Safety or Diagnostics, trading a detectable null for an undetectable lie. Real per-alarm
+classification is a separate future feature: it needs the driver's alarm category, which today lives
+only on the runtime `AlarmEventArgs` transition, carried to the deploy-time authored composition that
+`MaterialiseAlarmCondition` sees. Until then the `IAlarmSource` doc comment claiming the category
+"maps to `ConditionClassName` downstream" describes an intent, not the implementation.
+
+**Why `SourceName` is the id, not the leaf name.** The leaf is ambiguous across devices (`HR200` on
+two PLCs collides) and is already carried by `ConditionName`, so the leaf-name option would add no
+identity while costing uniqueness. Carrying the id makes the `SourceNode`/`SourceName`/`ConditionId`
+triple mutually consistent and unique. This diverges from the loose OPC UA convention that
+`SourceName` mirrors the source node's BrowseName; the divergence is intentional.
+
+**Client guidance:** key on **`ConditionId`** — the condition node's own NodeId, which equals
+`SourceNode`, and whose identifier is the RawPath for native alarms and the ScriptedAlarmId for
+scripted ones. It is the identity ack/confirm/shelve route on. `SourceName` carries the same
+identifier and is unique, so it is safe to key on *by itself* — but do **not** compose it with
+`ConditionName` (`$"{SourceName}.{ConditionName}"`), because `SourceName` already ends in the
+condition's leaf name and the result stutters (`pymodbus/plc/HR200.HR200`).
+
+Wire-level guard: `NativeAlarmEventIdentityFieldDeliveryTests` asserts the three `BaseEventType`
+fields arrive populated on a real subscription using the standard `[EventType, SourceNode,
+SourceName, Time, Message, Severity]` select clause, and — in a second test with its own clause —
+that `ConditionClassId` / `ConditionClassName` do too. The two class fields are declared on
+`ConditionType`, **not** `BaseEventType`, so a client must select them against that type.
+`NodeManagerAlarmSourceFieldsTests` guards the node itself across both realms.
+
+> **Do not correlate live events to HistoryRead on `SourceName` — the two paths disagree.**
+> The HistoryRead *events* projection (`OtOpcUaNodeManager.ProjectEventField`) returns
+> `Variant.Null` for `EventType` / `SourceNode` **by design**: it projects from the historian's
+> `HistoricalEvent` rows, which do not carry them. It **does** project `SourceName` — but the
+> alarm-history writer stamps that field with the **EquipmentPath**
+> (`AlarmEventMapper`: `SourceName = alarm.EquipmentPath`), not the RawPath a live event carries.
+> So `SourceName` is the one field populated on both paths **with different values**, and it is not
+> a live↔history join key. Correlate on `ConditionId` / the RawPath instead. (Pre-existing; the
+> live-path fix above does not change the history path.)
+
+### Condition source-data Quality (#477)
+
+`ConditionType.Quality` reports the quality of the condition's source data. It was never assigned, and
+because `StatusCodes.Good == 0x00000000` an unassigned `StatusCode` **is** `Good` — so every condition
+reported `Good` unconditionally (a wrong *value*, not a null like #473/#475). A native alarm whose device
+went offline still read `Good`, so an operator could not tell *"genuinely inactive"* from *"we have lost
+contact and do not know"*.
+
+**How it is driven now (native alarms).** An alarm-bearing raw tag materializes a condition with **no
+sibling value variable**, so the value/quality path (`WriteValue`) never touches it, and a comms-lost
+driver emits **no alarm transitions** (the feed goes silent). The quality therefore comes from the
+**driver's connectivity**, out of band from alarm transitions:
+
+- `DriverInstanceActor` Tells its host `ConnectivityChanged(driverInstanceId, connected)` on every
+  transition into `Connected` (`true`) / `Reconnecting` (`false`).
+- `DriverHostActor.OnDriverConnectivityChanged` fans that out to **every** native condition the driver
+  owns as an `OpcUaPublishActor.AlarmQualityUpdate` (`Good` on connect, `Bad` on disconnect).
+- `OtOpcUaNodeManager.WriteAlarmQuality` sets **only** the condition's `Quality` and fires a Part 9
+  event **only on a quality-bucket change** — it never touches Active/Acked/Severity/Retain (an active
+  alarm that loses comms stays active). This is a dedicated path, *not* a full-snapshot re-projection, so
+  it cannot clobber a condition's severity/message and works for a condition that never fired a transition.
+- A freshly materialized native condition starts `BadWaitingForInitialData` (the "no driver data yet"
+  convention value variables use); the first `Connected` confirms it `Good`.
+- The connectivity annotation is **ungated by redundancy role** (a Secondary keeps its condition quality
+  warm for failover) and publishes **no `/alerts` row** — driver comms health already has its own status
+  surface (`IDriverHealthPublisher`); a row per condition would be alarm-fatigue.
+
+**Scripted alarms (Layer 3, #478).** A scripted condition's state is computed from one or more input tags,
+so its `Quality` is the **worst** quality across those inputs at evaluation time ("can I trust this
+condition's state?") — mirroring the native OT semantic:
+
+- The mux now forwards each input's source quality (`DependencyValueChanged.Quality`), and the scripted host
+  pushes it into the engine's read cache (previously every mux value was treated as `Good`).
+- The `ScriptedAlarmEngine` computes the worst input quality each evaluation. A **real transition** carries
+  it on the emitted event → `ScriptedAlarmHostActor.ToSnapshot` projects it (so a transition fired while an
+  input is `Uncertain` does not clobber quality back to `Good`).
+- A **Bad input freezes the condition** (`AreInputsReady` holds its state — no transition), exactly like a
+  comms-lost native driver. So a quality-bucket change with no transition is emitted as
+  `EmissionKind.QualityChanged` and routed to the **same** dedicated `AlarmQualityUpdate → WriteAlarmQuality`
+  node path native uses (quality only, one Part 9 event on a bucket change, **no `/alerts` row**, no
+  historian write). `ScriptedAlarmSource` skips `QualityChanged` so it never fabricates a phantom
+  `IAlarmSource` event.
+- An input that has **not been published yet** (cold start) is *not* a quality signal (that is the readiness
+  guard's job) — it contributes `Good`, so scripted conditions don't flash `Bad` at every deploy. The first
+  actually-`Bad` published value flips the bucket and annotates.
+
+**Coverage boundary (#478 as shipped).** Scripted quality tracks input tags whose driver **publishes a
+data change carrying a Bad/Uncertain `StatusCode`** (e.g. an OpcUaClient input forwarding a server's
+per-item Bad). It does **not** yet cover a driver **comms loss**: a poll driver (Modbus/S7) whose device
+goes unreachable emits only `ConnectivityChanged` and goes *silent* on the value feed (see
+`DriverInstanceActor.Reconnecting`), so the scripted engine keeps the last-known Good value and the
+condition stays `Good`. Bridging driver connectivity into scripted inputs — the symmetric of the native
+`OnDriverConnectivityChanged` path above, plus resolving the null-value/cold-start asymmetry (a runtime
+`Bad` with a null value is currently indistinguishable from cold start and contributes `Good`) — is tracked
+as the Layer-4 follow-up (#481).
+
+Guards: `ScriptedAlarmEngineTests` (transition carries `Uncertain`; `Bad` input with no transition emits
+`QualityChanged(Bad)`; restore emits `QualityChanged(Good)`; unchanged bucket emits nothing),
+`ScriptedAlarmSourceTests.QualityChanged_emission_raises_no_alarm_event`,
+`DependencyMuxActorTests.Publish_quality_is_forwarded_on_DependencyValueChanged`, and
+`ScriptedAlarmHostActorTests` (`Bad_quality_dependency_publishes_AlarmQualityUpdate_and_no_alerts`,
+`Transition_snapshot_carries_worst_input_quality`).
+
+Wire-level guard: `NativeAlarmEventIdentityFieldDeliveryTests.Condition_event_Quality_tracks_source_connectivity_on_the_wire`
+subscribes with a `[Quality, Message]` clause (Quality is declared on `ConditionType`) and asserts a
+healthy source reports `Good`, a comms-lost source reports non-`Good`, and recovery returns to `Good` — on
+a real client subscription. `NodeManagerAlarmSourceFieldsTests` guards the node itself + the no-clobber /
+unknown-node-no-op invariants.
+
 ## Galaxy driver path (driver-native)

 Restored in PR B.2 of the epic. `GalaxyDriver` implements
@@ -146,6 +146,28 @@ key must carry the scopes `historian:read`, `historian:write`, `historian:tags:w
 [`docs/Historian.md`](Historian.md) for the full key reference, the migration note (old Wonderware keys →
 gateway keys), and the deployment prerequisites.

+### `LocalDb` (pair-local config cache — driver role only)
+
+Driver-role nodes keep a consolidated **`ZB.MOM.WW.LocalDb`** SQLite database that caches the deployed
+configuration artifact (chunked) so the node can **boot from cache when central SQL is unreachable**. The
+section is bound by `AddOtOpcUaLocalDb` (`Host/Configuration/LocalDbRegistration.cs`) inside the `hasDriver`
+branch — **admin-only nodes never register it, and never require `LocalDb:Path`**. Storage is unconditional;
+replication stays inert until the sync port + peer are set.
+
+| Key | Default | Meaning |
+|---|---|---|
+| `LocalDb:Path` | `./data/otopcua-localdb.db` | SQLite file path. `ValidateOnStart`-required once `AddZbLocalDb` runs (driver nodes only). In containers put it on a durable volume. |
+| `LocalDb:SyncListenPort` | `0` | `0` = replication off (no sync listener). A non-zero port binds a dedicated **h2c** sync listener; set the **same** port on both pair nodes. Setting it makes the Host add an explicit Kestrel `Listen*` and re-bind the primary HTTP port (an explicit `Listen*` otherwise discards `ASPNETCORE_URLS`). |
+| `LocalDb:Replication:PeerAddress` | `""` | The peer this node **dials** (`http://<peer>:<port>`). Set on the initiator only; leave empty on the passive node. The stream is bidirectional. |
+| `LocalDb:Replication:ApiKey` | `""` | Bearer token for the sync stream. **Fail-closed:** no key ⇒ the passive endpoint refuses everything; a mismatch ⇒ the pair silently stops converging. **Must be byte-identical on both nodes.** Supply via `${secret:...}` / env — never a cleartext literal in production. |
+| `LocalDb:Replication:MaxBatchSize` | (library default) | Rows per replication batch — **row-count-only** against gRPC's 4 MB cap. `16` for the artifact cache (chunk rows ≈171 KB, so 16 × 171 KB ≈ 2.7 MB). |
+
+Replication is **default-OFF** across the fleet; it is enabled per-pair as an opt-in. See
+[`docs/operations/2026-07-20-localdb-pair-replication.md`](operations/2026-07-20-localdb-pair-replication.md)
+for the enablement runbook (ApiKey handling, stop/start-together rule, tombstone-retention window, and the
+never-`sqlite3`-a-live-WAL-DB inspection rules) and the "pair-local config cache" section of
+[`docs/Redundancy.md`](Redundancy.md) for what boot-from-cache does and does not cover.
+
 ---

 ## Environment variables
@@ -199,6 +199,15 @@ The server supports all four OPC UA HistoryRead variants:
 `Historizing=true` and `AccessLevels.HistoryRead` are set at materialization so any compliant
 OPC UA client can discover historized capability from the node's attributes.

+> **v3 Batch 4 — dual-namespace registration.** A historized raw tag surfaces as **two**
+> variable nodes: the Raw-namespace node (`ns=Raw, s=<RawPath>`) and, for each referencing
+> equipment, a UNS-namespace node (`ns=UNS, s=<Area>/<Line>/<Equipment>/<EffectiveName>`).
+> **Both NodeIds register the SAME historian tagname** (the raw tag's `FullName` /
+> `historianTagname`), so HistoryRead against either NodeId resolves to the same tagname and
+> returns the same series. The historization intent is single-sourced — the mux's
+> `HistorizedTagRef` set stays keyed by RawPath (no doubles), and continuous historization /
+> `EnsureTags` provisioning run once per raw tag regardless of how many equipment reference it.
+
 **Equipment-folder event-notifier nodes** serve Event history. Every equipment folder that
 owns at least one alarm condition is already an event notifier; the server registers a
 `sourceName` (the equipment id) for each such folder and maps event history reads to the
@@ -355,31 +364,39 @@ for the full alarm-historian routing.
 The `historyread` command reads historical data from any node. Supply start and end times in
 ISO 8601 UTC form. See [docs/Client.CLI.md](Client.CLI.md) for the full flag reference.

+> **v3 Batch 4 NodeIds.** A historized tag is readable through **either** of its two NodeIds —
+> the Raw-namespace node (`s=<RawPath>`, e.g. `Plant/Modbus/dev1/Speed`) or a referencing
+> equipment's UNS-namespace node (`s=<Area>/<Line>/<Equipment>/<EffectiveName>`). Both register
+> the same historian tagname, so the returned series is identical. The `ns=N` index is assigned
+> at connect time per the namespace URI (`https://zb.com/otopcua/raw` /
+> `https://zb.com/otopcua/uns`) — resolve it from the server's `NamespaceArray` rather than
+> hard-coding it. The examples below show a Raw-namespace read (`ns=2` illustrative).
+
 ```bash
-# Raw history for a historized Galaxy tag (last 24 hours by default)
+# Raw history for a historized tag via its Raw-namespace NodeId (last 24 hours by default)
 otopcua-cli historyread \
  -u opc.tcp://localhost:4840/OtOpcUa \
-  -n "ns=2;s=EQ-55297329838d/GalaxyTestTag" \
+  -n "ns=2;s=Plant/Modbus/dev1/Speed" \
  --start "2026-06-13T00:00:00Z" --end "2026-06-14T00:00:00Z"

-# Limit to 100 values
+# Same series via a referencing equipment's UNS-namespace NodeId, limited to 100 values
 otopcua-cli historyread \
  -u opc.tcp://localhost:4840/OtOpcUa \
-  -n "ns=2;s=EQ-55297329838d/GalaxyTestTag" \
+  -n "ns=3;s=filling/line1/station1/Speed" \
  --start "2026-06-13T00:00:00Z" --end "2026-06-14T00:00:00Z" \
  --max 100

 # 1-hour average aggregate
 otopcua-cli historyread \
  -u opc.tcp://localhost:4840/OtOpcUa \
-  -n "ns=2;s=EQ-55297329838d/GalaxyTestTag" \
+  -n "ns=2;s=Plant/Modbus/dev1/Speed" \
  --start "2026-06-13T00:00:00Z" --end "2026-06-14T00:00:00Z" \
  --aggregate Average --interval 3600000

 # Authenticated read (ReadOnly role or higher required)
 otopcua-cli historyread \
  -u opc.tcp://localhost:4840/OtOpcUa \
-  -n "ns=2;s=EQ-55297329838d/GalaxyTestTag" \
+  -n "ns=2;s=Plant/Modbus/dev1/Speed" \
  --start "2026-06-13T00:00:00Z" --end "2026-06-14T00:00:00Z" \
  -U reader -P password
 ```
@@ -0,0 +1,91 @@
+# The Raw project tree (`/raw`)
+
+v3 authors device I/O in a **Raw project tree** — a cluster-rooted, Kepware-style hierarchy
+that is the single surface for driver/device/tag authoring. It is the peer of the `/uns`
+unified-namespace page; the two OPC UA namespaces (`ns=Raw` / `ns=UNS`) light up in Batch 4.
+
+```
+Enterprise → Cluster → Folder(s) → Driver → Device → TagGroup(s) → Tag
+```
+
+Every node's identity is its **RawPath** (`<Folder/…>/<Driver>/<Device>/<TagGroup/…>/<Tag>`,
+cluster-scoped, `/`-separated, ordinal). Names are validated as RawPath segments (no `/`, no
+leading/trailing whitespace) at authoring and at the deploy gate.
+
+## The tree
+
+`/raw` (`GlobalRaw.razor` → `RawTree.razor`, backed by `IRawTreeService`) lazily loads each
+container level on expand (unlike `/uns`, which eager-loads). Each node has a right-click
+context menu **and** a `⋯` fallback (the reusable `ContextMenu` component):
+
+| Node | Actions |
+|---|---|
+| Cluster | New folder · New driver |
+| Folder | New folder · New driver · Rename · Delete |
+| Driver | Configure · New device · Enable/Disable · Rename · Delete |
+| Device | Configure (endpoint + **Test connect**) · New tag-group · Add tags ▸ · Delete |
+| TagGroup | New group · Add tags ▸ · Rename · Delete |
+| Tag | Edit · Delete |
+
+Deletes are blocked while a node has children (or, for a raw tag, while a `UnsTagReference`
+points at it — the error names the referencing equipment). Renames return non-blocking
+**warnings**: renaming a node changes the RawPath of every historized / UNS-referenced tag
+beneath it (its historian tagname / UNS projection path moves).
+
+## Endpoint → DeviceConfig (the channel/device split)
+
+v3 moves the **connection endpoint** off the driver and onto the **Device** (`DeviceConfig`),
+mirroring Kepware's channel/device split. The driver's `DriverConfig` holds protocol/channel
+settings; the device's `DeviceConfig` holds host/port/endpoint. At deploy/probe time
+`DriverDeviceConfigMerger` merges the device's endpoint up into the driver config, and Test
+connect (inside the **Device** modal) probes that merged config. Driver forms no longer
+serialize the endpoint keys, so `DeviceConfig` is the single source of truth.
+
+## Authoring tags
+
+**Add tags ▸** on a Device or TagGroup offers:
+
+- **Manual entry** — a grid of Name / DataType / AccessLevel / WriteIdempotent / PollGroup +
+  the driver-typed `TagConfig` editor per row.
+- **Import/Export CSV** — a staged flow (upload → parse → **review grid** with per-row
+  verdicts → commit) over an RFC-4180 parser. Columns: the common set
+  (`Name, TagGroupPath, DataType, AccessLevel, WriteIdempotent, PollGroup, IsHistorized,
+  HistorianTagname, IsArray, ArrayLength, Alarm.*, TagConfigJson`) plus the per-driver typed
+  columns (e.g. Modbus `Region, Address, ModbusDataType, ByteOrder, …`). `TagGroupPath`
+  auto-creates nested groups; typed columns win over `TagConfigJson` on conflict (flagged in
+  the review grid). **Import is all-or-nothing** — any invalid row blocks the whole commit.
+  Export round-trips the same shape.
+- **Browse device…** — enabled per the two-tier resolution (bespoke `IDriverBrowser` →
+  universal `DiscoveryDriverBrowser` when the driver's `ITagDiscovery.SupportsOnlineDiscovery`
+  is true → grayed out otherwise). Multi-selected leaves become raw `Tag` rows under the
+  target, with the browsed reference written into the driver-typed `TagConfig` **address
+  field** (`nodeId` / `tagPath` / …), never an identity key. An opt-in "create matching
+  tag-groups" toggle mirrors the browse folder nesting. The browser dials a real ephemeral
+  driver against the **merged** Driver+Device config.
+
+## The `Calculation` driver
+
+Signal-level calculated tags are ordinary raw tags bound to a `Calculation` driver
+(`DriverTypeNames.Calculation`), computed by C# scripts that read other tags' live values via
+`ctx.GetTag("<RawPath>")`. See `docs/plans/2026-07-15-calculation-driver-mini-design.md` for
+the full design. Highlights:
+
+- One auto-created default `Engine` device; per-tag `TagConfig` is
+  `{ "scriptId": "…", "changeTriggered": true, "timerIntervalMs": 5000 }`.
+- The host feeds dependency values via the new `IDependencyConsumer` capability + a
+  `DependencyConsumerMuxAdapter` on the per-node dependency mux; calc-of-calc chains work
+  because a calc output re-enters the mux. The driver rebuilds its tag/dependency table on
+  every redeploy (`ReinitializeAsync`) and re-registers its refs after the delta applies.
+- **Deploy gates** (`DraftValidator`): `scriptId` existence, and a hard **cycle gate**
+  (`DependencyGraph.DetectCycles` over calc→calc edges; cross-driver refs are terminal) that
+  rejects an A→B→A oscillation loop naming the members. Compile is not hard-gated (VirtualTag
+  parity); a runtime compile/throw/timeout lands as Bad quality + a `script-logs` entry.
+
+## Retirement note
+
+The routed `/clusters/{id}/drivers` driver-authoring flow (`DriverTypePicker`,
+`DriverEditRouter`, the 8 per-type `*DriverPage` shells, and the per-cluster Drivers list) is
+**retired** — authoring lives in `/raw`. The extracted driver/device **form bodies** live on
+inside the `/raw` modals. The `DriverType` dispatch maps (`TagConfigEditorMap`,
+`TagConfigValidator`, `EquipmentTagConfigInspector`) are keyed off the single-source-of-truth
+`DriverTypeNames` constants (fixing the historical `TwinCat`/`Focas` drift).
@@ -226,6 +226,35 @@ Net effect: each alarm transition appears **once** on `/alerts` and would histor

 See [ScriptedAlarms.md](ScriptedAlarms.md) and [AlarmTracking.md](AlarmTracking.md) for the scripted-alarm engine internals.

+## Pair-local config cache (LocalDb — Phase 1)
+
+Independently of the ServiceLevel machinery above, every **driver-role** node keeps a consolidated
+[`ZB.MOM.WW.LocalDb`](../CLAUDE.md) SQLite database that caches the **deployed-configuration
+artifact** (chunked). Its job is a single failure mode redundancy does not otherwise cover: a driver
+node restarting into a **central-SQL-Server outage** would come up with no configuration at all. With
+the cache, it **boots from the last artifact it applied** instead, and logs a running-from-cache
+signal.
+
+- **What replicates.** The cache can *optionally* replicate to the node's redundant pair peer over
+  the LocalDb library's gRPC sync (HLC-stamped, last-writer-wins). Two tables replicate:
+  `deployment_artifacts` and `deployment_pointer`. Replication is **default-OFF and fail-closed** —
+  it stays inert until `LocalDb:SyncListenPort` + a peer are configured, and a missing/mismatched
+  `LocalDb:Replication:ApiKey` refuses or silently halts sync. It is enabled per-pair as an opt-in.
+- **The replicated-cache payoff.** In a pair with replication on, *either* node can be the one that
+  applied the latest deploy; the peer holds a byte-identical copy. So a node that restarts during a
+  central outage can boot the current config **even if it never applied that deploy itself** — its
+  peer did, and the row replicated.
+- **What it does NOT cover.** The cache is a **boot fallback for central-SQL outages only**, not a
+  standby data path and not a replacement for central. A **new deployment still requires central
+  SQL**; the cache is read only when the central fetch fails at startup, and the node resumes
+  fresh-config behavior once central returns. It does not replicate live tag values, alarms, or
+  historian data — only the config artifact. It is orthogonal to the ServiceLevel/primary-gate
+  logic: a node running from cache still participates in redundancy normally.
+
+Full detail: the enablement runbook at
+[`docs/operations/2026-07-20-localdb-pair-replication.md`](operations/2026-07-20-localdb-pair-replication.md)
+and the `LocalDb` section of [`docs/Configuration.md`](Configuration.md).
+
 ## Client-side failover

 The OtOpcUa Client CLI at `src/Client/ZB.MOM.WW.OtOpcUa.Client.CLI` supports `-F` / `--failover-urls` for automatic client-side failover; for long-running subscriptions the CLI monitors session KeepAlive and reconnects to the next available server, recreating the subscription on the new endpoint. See [`Client.CLI.md`](Client.CLI.md).
@@ -212,6 +212,13 @@ The catalog is scoped per Blazor circuit; each call creates and disposes its own
 `DbContext` via the pooled factory (same pattern as `UnsTreeService`). Results
 are bounded to 200 entries to keep the completion list responsive on large fleets.

+> **v3 Batch 4 (dual namespace) — unchanged for scripts.** A `ctx.GetTag(...)` literal
+> still resolves by the tag's `FullName` / **RawPath** — which is precisely the identity
+> of the Raw-namespace node (`ns=Raw, s=<RawPath>`). A `{{equip}}/<RefName>` token resolves
+> through the equipment's `UnsTagReference` to that same backing RawPath (see below), so
+> scripts key off the single value source regardless of the UNS projection. The dual
+> namespace changes only the OPC UA address-space surface, not script tag-path semantics.
+
 ### Literal gate

 `TryGetTagPathLiteral` identifies the tag-path context by climbing from the
@@ -307,76 +314,88 @@ Register the replacement in `EndpointRouteBuilderExtensions.AddAdminUI`

 ### Why

-Today each VirtualTag bound to a script typically needs its own near-duplicate
-script because tag paths are hard-coded absolutes (e.g. `TestMachine_001.Speed`).
-The `{{equip}}` token breaks this coupling: point many VirtualTags' `ScriptId` at
-a single template script, and each resolves the token to its own equipment's tag
-base prefix at deploy time. No schema change is required — sharing a `Script`
-record across VirtualTags already works; `{{equip}}` is what makes the shared
-script resolve per-equipment.
+Each VirtualTag bound to a script would otherwise need its own near-duplicate
+script because tag paths are hard-coded absolute RawPaths (e.g.
+`Cell1/Modbus/Dev1/Speed`). The `{{equip}}/<RefName>` token breaks this coupling:
+point many VirtualTags' `ScriptId` at a single template script, and each resolves
+the token through **its own equipment's tag references** at deploy time. No schema
+change is required — sharing a `Script` record across VirtualTags already works;
+`{{equip}}/<RefName>` is what makes the shared script resolve per-equipment.

 ### Before / after

-**Before — one script per machine:**
+**Before — one script per machine (hard-coded RawPath):**

 ```csharp
 // Script "Calc_TestMachine_001" — hard-coded, cannot reuse
-return ctx.GetTag("TestMachine_001.Speed").Value;
+return ctx.GetTag("Cell1/Modbus/Dev1/Speed").Value;
 ```

 **After — one shared template:**

 ```csharp
 // Script "Calc_Speed" — works for any machine
-return ctx.GetTag("{{equip}}.Speed").Value;
+return ctx.GetTag("{{equip}}/Speed").Value;
 ```

-`TestMachine_001` and `TestMachine_002` both bind `ScriptId = "Calc_Speed"`.
-At deploy, each VirtualTag receives its own expanded copy:
-`TestMachine_001.Speed` and `TestMachine_002.Speed` respectively.
+`TestMachine_001` and `TestMachine_002` both bind `ScriptId = "Calc_Speed"`, and
+each has a **tag reference** whose effective name is `Speed`. At deploy, each
+VirtualTag receives its own expanded copy — `{{equip}}/Speed` resolves to that
+equipment's referenced raw tag's RawPath.

-### Token rules
+### Token rules (v3)

- The token is `{{equip}}` (double braces, lowercase).
+- The token joint is a **slash**: `{{equip}}/<RefName>` (double-brace stem,
+  lowercase). `<RefName>` is a **reference effective name** — the reference's
+  `DisplayNameOverride`, else the backing raw tag's `Name`.
 - It is substituted **only inside `ctx.GetTag(…)` / `ctx.SetVirtualTag(…)` first-argument
  string literals** — comments, logger strings, and other code are untouched.
- The operator writes the separator and tail: `ctx.GetTag("{{equip}}.Speed")`,
-  `ctx.GetTag("{{equip}}.Sub.Field")`, etc.
- The token expands to the equipment's **tag base prefix** — the common
-  substring-before-the-first-dot of that equipment's configured driver-tag
-  `FullName` values. Example: tags `TestMachine_001.Speed` and
-  `TestMachine_001.Temp` → base `TestMachine_001`.
+- The whole post-prefix literal content is the reference name, so effective names
+  with internal spaces are supported: `ctx.GetTag("{{equip}}/Motor Speed")`.
+- `{{equip}}/<RefName>` **resolves through the owning equipment's `UnsTagReference`
+  rows** (by effective name) to the backing raw tag's `RawPath`. Example: a
+  reference named `Speed` backing `Cell1/Modbus/Dev1/Speed` → the token expands to
+  `Cell1/Modbus/Dev1/Speed`.
+- Scripted-alarm predicate scripts resolve `{{equip}}/<RefName>` the same way; alarm
+  **message-template** tokens follow the same resolution rule.

 ### Validation requirement

-Saving a VirtualTag that is bound to a `{{equip}}`-using script is rejected in
-the AdminUI if the equipment does not have at least one configured driver tag, or
-if its tags span multiple object prefixes (i.e. the common prefix is ambiguous or
-absent). The rejection message is surfaced as a clear validation error on the save
-form. This check is enforced eagerly so that an unresolved `{{equip}}` token —
-which would leave a path that resolves to nothing at runtime (Bad quality) — can
-never reach the deployed artifact.
+Saving a VirtualTag (or ScriptedAlarm) whose script uses `{{equip}}/<RefName>` is
+rejected in the AdminUI when `<RefName>` is not one of the owning equipment's
+reference effective names. The same rule runs at the deploy gate
+(`DraftValidator.ValidateEquipReferenceResolution`, error code
+`EquipReferenceUnresolved`), which also catches a **rename-induced** breakage the
+authoring check never saw. The rejection names the script/alarm, the equipment, and
+the missing ref — so an unresolved token can never reach the deployed artifact.

 ### Editor support

 In the Monaco script editor (ScriptEdit page and the `/uns` virtual-tag modal's
 inline script panel):

- **Hover** — hovering a `{{equip}}` path literal shows an
-  *"Equipment-relative path — resolved at deploy"* note.
- **Completions** — typing `{{equip}}.` inside a `GetTag`/`SetVirtualTag` literal
-  offers completion of attribute leaf names (the part after the first dot of known
-  tag references in the catalog).
+- **Hover** — hovering a `{{equip}}/<RefName>` path literal shows an
+  *"Equipment-relative path — resolved through the equipment's tag reference at
+  deploy"* note.
+- **Completions** — typing `{{equip}}/` inside a `GetTag`/`SetVirtualTag` literal
+  offers the owning equipment's **reference effective names** (needs an equipment
+  context; inert on the shared ScriptEdit page).
+- **Diagnostics** — an unresolved `{{equip}}/<RefName>` is flagged (`OTSCRIPT_EQUIPREF`)
+  identically to the deploy gate, preserving *editor accepts ⇔ publish accepts*.

 ### Maintainer note

-Substitution runs at the two compose seams —
-`Phase7Composer.Compose` and `DeploymentArtifact.BuildEquipmentVirtualTagPlans`
-— via the shared `ZB.MOM.WW.OtOpcUa.Commons.Types.EquipmentScriptPaths` helper,
-**before** dependency extraction. The runtime, the static change-trigger
-dependency graph, and the literal-only path rule are therefore all unchanged:
-by the time they see the script, `{{equip}}` has been replaced with a concrete
-tag-base prefix and the path is a normal string literal.
+Substitution runs at the two compose seams — `AddressSpaceComposer.Compose` and
+`DeploymentArtifact.ParseComposition` — via the shared
+`ZB.MOM.WW.OtOpcUa.Commons.Types.EquipmentScriptPaths.SubstituteEquipmentToken`
+helper, fed the equipment's reference map (effective name → RawPath) built by
+`EquipmentReferenceMap` over the shared `RawPathResolver`. Substitution runs
+**before** dependency extraction, so the runtime, the static change-trigger
+dependency graph, and the literal-only path rule are unchanged: by the time they
+see the script, `{{equip}}/<RefName>` has been replaced with a concrete RawPath and
+the path is a normal string literal. An unresolved ref is left un-substituted (the
+validator rejects it first — substitution never throws). The two seams build the
+reference map identically, so their plans stay byte-parity.

 ---

@@ -127,9 +127,25 @@ object alongside the usual `"FullName"`:
 (unchanged behaviour). `"alarm"` **present** → the tag materialises as a Part 9
 `AlarmConditionState` under its equipment folder **instead of** a value variable.
 No EF/schema change is required; the intent rides in the schemaless `TagConfig`
-blob and is parsed byte-parity in both the compose (`Phase7Composer`) and deploy
+blob and is parsed byte-parity in both the compose (`AddressSpaceComposer`) and deploy
 (`DeploymentArtifact`) paths.

+> **v3 Batch 4 — multi-notifier fan-out.** The `"alarm"` object now rides on a **raw
+> tag** authored in `/raw` (referenced into equipment), and the Part 9 condition
+> materializes **once at the raw tag** — its `ConditionId` is the tag's **RawPath**, its
+> parent notifier is the raw device/group folder. For **each referencing equipment**, the
+> node manager (`WireAlarmNotifiers`) wires the SDK `AddNotifier` pattern
+> (`alarm.AddNotifier(equipFolder, isInverse:true)` + `equipFolder.AddNotifier(alarm)` +
+> `EnsureFolderIsEventNotifier(equipFolder)`) so the single condition fans to the raw device
+> folder AND every equipment folder. A **single** `ReportEvent` fans to all notifier roots —
+> a Server-object subscriber sees **exactly one** copy (the Part 9 shared-snapshot dedup),
+> never one-per-root. Teardown is symmetric (`RemoveNotifier(..., bidirectional:true)` on
+> rebuild / reference removal) so inverse-notifier entries never leak across redeploys.
+> Ack/confirm/shelve route on **`ConditionId = RawPath`** (never `SourceNodeId`), and the
+> `/alerts` row lists the referencing equipment paths. See
+> [AlarmTracking.md](AlarmTracking.md) and the WP4 section of
+> `docs/plans/2026-07-15-v3-batch4-address-space-plan.md`.
+
 ### TagConfig alarm fields

 | Field | Values | Default |
@@ -208,9 +224,10 @@ native alarm transitions identically. Publication to the `alerts` topic is
 the OPC UA condition-node write is ungated on all nodes so a Secondary stays warm
 for failover.

-The alarm is authored on the `Tags` tab of the equipment page (`/uns/equipment/{id}`)
-by editing the tag's raw `TagConfig` JSON to include the `"alarm"` object. No
-other configuration is required.
+The alarm is authored on the **raw tag** in `/raw` by including the `"alarm"` object in the
+tag's `TagConfig` JSON (v3 Batch 4 — equipment no longer authors tags; it references raw
+tags). No other configuration is required: any equipment that references the raw tag
+automatically receives the alarm at its equipment folder via the multi-notifier fan-out above.

 ### Native-alarm OPC UA operator operations

@@ -74,26 +74,88 @@ 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
+### Tags — reference-only (v3)

-Tags created on the equipment page are **equipment-bound** and require a driver
-instance. The driver list on the Tags tab is scoped to the equipment's cluster
-and to drivers on an **Equipment-kind** namespace, so a driver-less equipment
-shows no eligible drivers until you bind one (edit the equipment on the Details
-tab and pick a driver).
+> **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.

-**Galaxy / AVEVA System Platform points are ordinary equipment tags** bound to
-a `GalaxyMxGateway` driver instance. Author them on the Tags tab using the
-standard Tag modal; the Galaxy address picker browses the live Galaxy hierarchy
-so you can select the attribute and set `TagConfig.FullName`. There is no
-separate alias concept or `SystemPlatform`-kind namespace.
+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.
+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

@@ -0,0 +1,177 @@
+# Secrets: Clustered Master-Key Posture (All Roles)
+
+## Purpose
+
+`ZB.MOM.WW.Secrets` resolves `${secret:...}` tokens in `appsettings.*.json` via a
+pre-host expander (`SecretReferenceExpander.ExpandConfigurationAsync`, wired in
+`src/Server/ZB.MOM.WW.OtOpcUa.Host/Program.cs`) that runs at **every** OtOpcUa node
+boot, before the host is built. It reads rows from an envelope-encrypted SQLite
+store (`Secrets:SqlitePath`) unwrapped with a key-encryption key (KEK) sourced per
+`Secrets:MasterKey:Source`. The runtime `ISecretResolver` (`AddZbSecrets`) is also
+registered unconditionally, independent of node role.
+
+OtOpcUa is Akka.NET-clustered (`builder.Services.AddAkka("otopcua", (ab, sp) => { ... })`
+in `Program.cs`), with roles parsed by `RoleParser` (`src/Core/ZB.MOM.WW.OtOpcUa.Cluster/RoleParser.cs`):
+`admin`, `driver`, `dev`. A node can carry any combination of these roles (e.g. a
+fused admin+driver node, or a driver-only node). This runbook covers what a
+production deployment needs so that secret resolution behaves identically on
+**every node regardless of role** — not just admin nodes. That matters here more
+than it might elsewhere: the pre-host expander and the runtime resolver both run
+unconditionally on driver-only nodes too, and driver-only nodes are the ones that
+will resolve Layer-B `DriverConfig` secret references (coming in Slice 2) at
+runtime, not just at boot. It does **not** change any code; it is an
+operations/deployment posture, delivered out-of-band from the committed config.
+
+## The two hard requirements
+
+For the pre-host expander (and the runtime resolver) to resolve the same
+plaintext secret on every node, no matter its role:
+
+1. **Identical KEK on every node.** All nodes — admin, driver, and any fused
+   combination — must unwrap the store with the exact same master key. A
+   per-node KEK (e.g. a per-box DPAPI-protected key) would make each node
+   decrypt every *other* node's ciphertext rows to garbage.
+2. **Identical store rows on every node.** All nodes must read the same SQLite
+   database (same file, or a replicated/shared copy with the same rows) — not
+   independently-seeded stores that happen to share a KEK.
+
+`ZB.MOM.WW.Secrets` ships a SQLite-only `ISecretStore` with a `NoOpSecretReplicator`
+— there is no built-in cross-node replication today. Meeting both requirements in
+production is a deployment concern, covered below.
+
+## Recommended interim posture (G-5)
+
+Until real replication exists (G-7, below), the recommended production posture is:
+
+- **`Secrets:MasterKey:Source = File`**, with `FilePath` pointing at a **read-only
+  key file that is identical on every node of every role** — a base64-encoded
+  32-byte key, generated out-of-band (e.g. `openssl rand -base64 32`), distributed
+  to each node's filesystem/secret-mount by the deployment tooling, and **never
+  committed** to the repo. Treat it with the same discipline as any other
+  production secret (restrictive file ACLs, no logging, rotated via a future
+  KEK-rotation runbook — not yet built).
+- **`Secrets:SqlitePath`** pointing at a **single shared or replicated volume**
+  that every node mounts (admin, driver, and dev/fused alike), so every node's
+  migrator opens and reads the same rows at boot.
+
+Writes to the store are rare and human-driven — an operator using the
+`/admin/secrets` UI (admin nodes only) or the `ZB.MOM.WW.Secrets` CLI — while
+reads happen on every node's boot and on the `ResolveCacheTtl` refresh cycle,
+regardless of role. The access pattern is read-mostly / effectively
+single-writer, which is what makes a shared SQLite volume viable as an interim
+posture (see caveat below).
+
+## How it's delivered (do NOT commit these values)
+
+The File-KEK + shared-store posture is supplied per-node at deployment time —
+**never** by editing the committed `appsettings.json` or the role-overlay files
+(`appsettings.admin.json`, `appsettings.driver.json`, `appsettings.admin-driver.json`).
+Those committed overlays are also consumed by local dev and the
+`TwoNodeClusterHarness` integration tests, so hardcoding a `Source=File` path
+into them would break every dev/test/CI boot. Two acceptable delivery
+mechanisms instead:
+
+**Option A — environment variable overrides** (Windows Service / NSSM env block,
+container `env_file`, etc.), applied identically on every node regardless of role:
+
+```
+# production deployment — do not commit to the dev appsettings
+Secrets__MasterKey__Source=File
+Secrets__MasterKey__FilePath=/run/secrets/otopcua-master.key
+Secrets__SqlitePath=/shared/secrets/otopcua-secrets.db
+```
+
+**Option B — a production-only config layer** that is *not* the committed dev
+base (e.g. an untracked `appsettings.Production.json` deployed alongside the
+binaries, or an orchestrator-injected config mount):
+
+```jsonc
+// production deployment — do not commit to the dev appsettings
+{
+  "Secrets": {
+    "MasterKey": {
+      "Source": "File",
+      "FilePath": "/run/secrets/otopcua-master.key"
+    },
+    "SqlitePath": "/shared/secrets/otopcua-secrets.db"
+  }
+}
+```
+
+Either way, the file/path referenced must exist and be identical on every node
+**before** that node boots — the pre-host expander runs unconditionally on every
+role and will throw (`SecretNotFoundException` / migration failure) if the store
+or key is missing.
+
+## Caveat: SQLite over a shared volume is not real replication
+
+SQLite's file-locking model does not tolerate concurrent multi-writer access well
+over network filesystems (SMB/NFS locking is unreliable, and even on a clustered
+block volume only one writer should be active at a time). The interim posture
+above is acceptable because:
+
+- Reads dominate (every node's boot + cache-refresh cycle, across every role).
+- Writes are rare, human-initiated, and effectively single-writer in practice
+  (an operator runs the CLI/UI against one admin node at a time).
+
+It is **not** a substitute for real replication, and it is not safe if multiple
+nodes attempt concurrent writes. Do not build automation that writes secrets
+from more than one node simultaneously.
+
+## Data Protection is independent — do not touch it here
+
+OtOpcUa's cookie/session protection already has its own clustered-key story:
+`AddDataProtection().PersistKeysToDbContext<OtOpcUaConfigDbContext>()`
+(`src/Server/ZB.MOM.WW.OtOpcUa.Security/ServiceCollectionExtensions.cs:73-75`),
+which shares the Data Protection key ring across every node via the existing
+ConfigDb. That mechanism is unrelated to `ZB.MOM.WW.Secrets`' envelope encryption
+(KEK + SQLite store) and must **not** be reconfigured as part of secrets-adoption
+work — doing so risks invalidating active sessions for an unrelated reason.
+
+It is, however, the model for where the *next* iteration of secret storage
+should go — see the G-7 hand-off below.
+
+## The G-7 hand-off
+
+The posture above is an interim, ops-only workaround. The long-term shape,
+tracked as **G-7** in `scadaproj/components/secrets/GAPS.md`, is a
+ConfigDb-backed `ISecretStore` that mirrors the pattern OtOpcUa already uses for
+the Data Protection key ring:
+
+```csharp
+services.AddDataProtection()
+    .PersistKeysToDbContext<OtOpcUaConfigDbContext>()
+    .SetApplicationName("OtOpcUa");
+```
+
+(`src/Server/ZB.MOM.WW.OtOpcUa.Security/ServiceCollectionExtensions.cs:73-75`).
+`OtOpcUaConfigDbContext` already gives every node — admin, driver, and dev/fused
+alike — a single MS SQL-backed source of truth for the Data Protection key ring;
+the secret store is the natural next tenant of that same shared database instead
+of a shared SQLite file. Building this requires new `ZB.MOM.WW.Secrets` library
+code (a ConfigDb-backed `ISecretStore` implementation) that does not exist yet,
+overlaps the G-7 tracking item, and is explicitly **deferred there** — it is not
+built as part of this cut. This runbook's shared-SQLite-volume posture is the
+bridge until G-7 lands.
+
+## Dev/test/default posture (unchanged)
+
+The committed default in `appsettings.json` is:
+
+```json
+"Secrets": {
+  "SqlitePath": "otopcua-secrets.db",
+  "MasterKey": { "Source": "Environment", "EnvVarName": "ZB_SECRETS_MASTER_KEY" },
+  "RunMigrationsOnStartup": true
+}
+```
+
+This is dev-safe: `Source=Environment` needs no filesystem key, and the SQLite
+path is relative to the working directory, so local dev, the role-overlay
+appsettings (`appsettings.admin.json`, `appsettings.driver.json`,
+`appsettings.admin-driver.json`), and the `TwoNodeClusterHarness` integration
+tests all boot cleanly with no external mount. The File-KEK + shared-volume
+posture in this runbook applies only to real clustered production deployments —
+it must never be baked into the committed dev/role-overlay base, because the
+expander runs unconditionally at every node boot (any role) and would break
+dev/CI if pointed at a nonexistent `/shared` mount.
@@ -0,0 +1,136 @@
+# LocalDb pair replication — operations runbook
+
+> **Phase 1 scope.** Every driver-role OtOpcUa node keeps a consolidated
+> [`ZB.MOM.WW.LocalDb`](../../CLAUDE.md) SQLite database. Today it caches exactly one thing: the
+> **deployed-configuration artifact**, chunked, so a node can **boot from cache when central SQL
+> Server is unreachable**. That cache can *optionally* replicate to the node's redundant pair peer
+> over the library's gRPC sync. **Replication is default-OFF and fail-closed.** This runbook covers
+> enabling it, the operational rules that keep a pair converging, and the DB-inspection safety
+> rules.
+
+## What replicates, and what it buys you
+
+- **Replicated tables:** `deployment_artifacts` (the artifact, split into base64 chunks) and
+  `deployment_pointer` (one current-deployment pointer per cluster). Registered — in this order,
+  after the DDL — by `LocalDbSetup.OnReady`.
+- **The payoff:** in a redundant driver pair, *either* node can be the one that applied the latest
+  deploy and wrote the cache. With replication on, the peer holds a byte-identical copy. So a node
+  that restarts into a central-SQL outage can boot the current config **even if it never applied
+  that deploy itself** — its peer did, and the row replicated.
+- **Convergence model:** last-writer-wins per primary key, HLC-stamped. Both nodes also store
+  locally after every apply, so the pair converges to identical content regardless of which node
+  deployed. Retention (newest-2 deployments per cluster) prunes on one node and the deletes
+  replicate as tombstones.
+
+## Enabling replication on a pair
+
+Replication has two knobs, both under `LocalDb`:
+
+| Key | Role | Notes |
+|---|---|---|
+| `LocalDb:SyncListenPort` | binds the dedicated **h2c** sync listener | `0` (default) = no listener, replication off. Set the **same** non-zero port on **both** nodes of the pair. |
+| `LocalDb:Replication:PeerAddress` | the address this node **dials** | Set on **one** node (the initiator); leave empty on the other (passive). The stream is bidirectional — one dial carries both directions. |
+| `LocalDb:Replication:ApiKey` | bearer token for the sync stream | **Must be byte-identical on both nodes.** See fail-closed rule below. Supply via `${secret:...}` / env — never a cleartext literal in production config. |
+| `LocalDb:Replication:MaxBatchSize` | rows per replication batch | `16` for the artifact cache. Batching is **row-count-only** against gRPC's 4 MB message cap; artifact chunk rows are ≈171 KB, so 16 × 171 KB ≈ 2.7 MB stays under the cap. Raising it risks tripping the cap. |
+
+Example (site-a-1 initiator, site-a-2 passive):
+
+```
+site-a-1:  LocalDb__SyncListenPort=9001
+           LocalDb__Replication__PeerAddress=http://site-a-2:9001
+           LocalDb__Replication__ApiKey=${secret:site-a-localdb-sync-key}
+           LocalDb__Replication__MaxBatchSize=16
+site-a-2:  LocalDb__SyncListenPort=9001
+           LocalDb__Replication__ApiKey=${secret:site-a-localdb-sync-key}   # no PeerAddress
+           LocalDb__Replication__MaxBatchSize=16
+```
+
+> **Kestrel note.** Setting `SyncListenPort` makes the Host add an explicit `Listen*` for the h2c
+> sync listener. An explicit `Listen*` makes Kestrel **ignore `ASPNETCORE_URLS` entirely**, so the
+> Host also re-binds the primary HTTP port in the same block. If you change the primary port,
+> verify both `:<httpPort>` and `:<syncPort>` appear in the startup "Now listening on" lines.
+
+### The ApiKey rule (fail-closed)
+
+The replication library's passive endpoint verifies **no** authentication — the host
+`LocalDbSyncAuthInterceptor` is the only gate, and it is **fail-closed**:
+
+- **No key configured ⇒ every sync call is refused** (`PermissionDenied`). "No key" is never
+  "no auth required".
+- **A key mismatch ⇒ the pair silently stops converging.** The initiator's stream is rejected at
+  the peer; nothing errors loudly. A typo in one node's key looks exactly like "replication is
+  broken". If a pair is not converging, **check the keys match first.**
+
+## Operational rules
+
+- **Stop / start the pair together where you can.** Each node keeps working (and caching locally)
+  while its peer is down; the outage is not a data-loss event — the surviving node accumulates
+  writes and the peer catches up on rejoin. But a long-lived solo node drifts further from its
+  peer, so avoid leaving a pair split for extended periods.
+- **Tombstone-retention resurrection window.** Retention prunes to the newest 2 deployments and
+  replicates the prune as tombstones. Tombstones are themselves retained only for a bounded window.
+  If a node is offline **longer than the tombstone-retention window**, a delete that happened during
+  its outage may no longer be expressible as a tombstone on rejoin — a pruned deployment could
+  briefly reappear until the next deploy re-prunes it. Keep pair outages well inside that window.
+- **A rebuilt node is back-filled by its peer.** If a node loses its LocalDb file — a wiped volume,
+  a re-imaged host, a fresh container — it rejoins with an empty database and its peer snapshots the
+  cached configuration back to it, with no new deploy and no central SQL. Two things are worth
+  knowing: this needs **`ZB.MOM.WW.LocalDb` ≥ 0.1.3**, and it heals the *cache*, so the node regains
+  boot-from-cache for future outages. (On `0.1.1` a converged pair has pruned every oplog row on ack
+  and the wiped node was never snapshotted — it stayed empty until the next deploy. On `0.1.2` it is
+  back-filled but its OWN writes are silently dropped until its restarted seq counter climbs past the
+  peer's stale watermark, so the pair looks converged right up until the moment only the rebuilt node
+  applies a deploy.) A node
+  wiped **during** a central outage is still repopulated by its peer under 0.1.2; a node with **no**
+  peer replication configured self-heals only from central on its next successful apply.
+
+- **What boot-from-cache does NOT cover.** The cache is a *fallback for central-SQL outages at
+  boot*, not a replacement for central. A **new deployment still requires central SQL** — the cache
+  is only read when the central fetch fails at startup. When central returns, the node resumes
+  fresh-config behavior. Boot-from-cache logs a running-from-cache signal; treat a node that stays
+  on it as a central-connectivity incident, not steady state.
+
+## Inspecting the LocalDb file — safety rules
+
+The database runs in **WAL mode**. These rules exist because violating them corrupted a live DB in
+the 2026-07-20 ScadaBridge incident:
+
+- **Never run `sqlite3` on the live file** (host-side, against a bind-mounted or container path).
+  Opening a live WAL DB from a second process across virtiofs poisons the WAL. **Always copy the
+  triplet first** and query the copy:
+
+  ```bash
+  docker cp <node>:/app/data/otopcua-localdb.db      /tmp/localdb.db
+  docker cp <node>:/app/data/otopcua-localdb.db-wal  /tmp/localdb.db-wal
+  docker cp <node>:/app/data/otopcua-localdb.db-shm  /tmp/localdb.db-shm
+  sqlite3 /tmp/localdb.db 'SELECT cluster_id, deployment_id FROM deployment_pointer;'
+  ```
+
+- **Metrics** come from the container, not a host curl (`aspnet:10.0` has no `curl`):
+
+  ```bash
+  docker run --rm --network container:<node> curlimages/curl:latest -s localhost:<httpPort>/metrics | grep localdb_
+  ```
+
+- **If an anomaly appears within seconds of your own measurement, suspect the measurement.**
+  Restart both nodes and re-observe untouched before blaming the library.
+
+## Useful queries (on a copied triplet)
+
+```sql
+-- What each node thinks the current deployment is
+SELECT cluster_id, deployment_id, revision_hash, applied_at_utc FROM deployment_pointer;
+
+-- Convergence check: the pointer's origin stamp should match on both nodes
+SELECT pk_json, hlc, node_id, is_tombstone
+FROM __localdb_row_version WHERE table_name = 'deployment_pointer' ORDER BY pk_json;
+
+-- Replication backlog (should drain to 0 when a pair is caught up)
+SELECT COUNT(*) FROM __localdb_oplog;
+```
+
+## See also
+
+- [`docs/Redundancy.md`](../Redundancy.md) — the pair-local config cache section.
+- [`docs/Configuration.md`](../Configuration.md) — the `LocalDb` appsettings section.
+- The two-node convergence harness: `tests/Server/ZB.MOM.WW.OtOpcUa.Host.IntegrationTests/LocalDb/`.
@@ -0,0 +1,74 @@
+# v3 Batch 2 — `/raw` project-tree AdminUI + `Calculation` driver
+
+Implements `docs/plans/2026-07-15-v3-batch2-raw-ui-calculation-plan.md` (Track 0 + WP1–WP8),
+executed via the `/v3-batch 2` coordinator: contracts-first fan-out, worktree-isolated Opus
+agents per wave, a code-reviewer pass + green build/test after each wave, then the
+non-negotiable 7-item live gate on docker-dev.
+
+## What landed
+
+- **Track 0** — reusable `ContextMenu` (right-click + `⋯`, keyboard/focus); RFC-4180
+  `CsvParser`/`CsvWriter`; `DriverTypeNames` constants + a reflection-discovery guard;
+  `CalculationEvaluator` core (VirtualTag-evaluator parity).
+- **Wave A** — `IRawTreeService`/`RawTreeService` (lazy tree + mutations, integrity guards,
+  rename-warnings); `/raw` page + lazy `RawTree` with per-node context menus.
+- **Wave B** — driver→embeddable-form refactor + `DriverConfigModal`/`DeviceModal`
+  (endpoint→`DeviceConfig`, Test-connect via merged config); manual tag entry + tag edit
+  modal + `Calculation` tag editor; CSV import (staged review grid) / export; all wired into
+  the tree (name/confirm/driver-type dialogs + post-mutation refresh).
+- **Wave C** — browse re-target (two-tier gate, merged-config feed, commit → raw tags with
+  address-field mapping + folder mirroring); `Calculation` driver (`IDependencyConsumer` +
+  mux adapter, timer + change triggers, `DraftValidator` scriptId + cycle gates);
+  `DriverTypeNames` rewire + retirement of the routed driver flow.
+
+**Address space stays dark** (values light up in Batch 4). Full solution builds 0 errors;
+`AdminUI.Tests` 638 passed / 3 skipped, `Runtime.Tests` 357 passed, driver + guard suites green.
+
+## Reviewer findings fixed in-branch
+
+- **Wave B H1** — driver forms still serialized the endpoint into `DriverConfig`; stripped
+  the endpoint keys (Modbus/S7/OpcUaClient) so `DeviceConfig` is the sole source (a 2nd
+  device on a single-Host driver no longer reverts to `127.0.0.1`).
+- **Wave C HIGH** — `CalculationDriver.ReinitializeAsync` ignored the new config, so calc
+  tag/script edits were silently inert after a redeploy and the re-register loop was
+  decorative. Now rebuilds the tag/dependency table on reinit and re-registers deps after
+  the delta applies (`DeltaApplied` notification, race-free). New redeploy test proves it.
+- Wave-A/B/0 mediums (auto-expand, friendly create-race/delete failures, discovery-driven
+  guard, CSV comment). Deferred (documented): pre-existing Modbus/S7 form `TimeSpan`↔`*Ms`
+  DTO mismatch; CSV alarm-subfield/flag-precedence edge cases; OpcUaClient endpoint
+  precedence; unused `LoadMergedProbeConfigAsync`; refresh collapses sibling expansion.
+
+## Live `/run` gate (docker-dev `:9200`, both central nodes rebuilt)
+
+1. **Authoring + Test-connect** — `/raw` → New Modbus driver `gate-modbus` (form body renders,
+   `PLC family`/`MELSEC` enum dropdowns correct) → Device1 endpoint `10.100.0.35:5020` in
+   `DeviceConfig` → **Test connect OK · 94 ms** against the live Modbus fixture; SQL confirms
+   endpoint in `DeviceConfig` (`{"Host":"10.100.0.35","Port":5020,"UnitId":1}`).
+2. **Historian-tagname deploy block** — a historized tag with a 260-char effective tagname →
+   `POST /api/deployments` **422** `[HistorianTagnameTooLong] tag 'TAG-gatelong' … is 260 chars
+   (max 255)`; shortened override → **202 Accepted**.
+3. **CSV round-trip + bad-enum** — export produces the exact column dictionary
+   (`…,Region,Address,ModbusDataType,ByteOrder,…`); importing 1 valid + 1 bad-enum row →
+   review grid "2 rows, 1 valid, 1 invalid", row-2 error *"Column 'ModbusDataType':
+   'NOTATYPE' is not a valid ModbusDataType (expected one of: Bool, Int16, UInt16, …)"*,
+   **Commit disabled** (all-or-nothing; SQL confirms nothing committed); a valid-only import →
+   Commit → `ImportedTag` lands with typed columns assembled into `TagConfig`.
+4. **Browse-commit** — OpcUaClient device → opc-plc (`opc.tcp://10.100.0.35:50000`): two-tier
+   gate enabled browse, merged config connected, real tree walked (NetworkSet/…/OpcPlc);
+   multi-selected 2 leaves with "create matching tag-groups" → raw tags land under the
+   mirrored `Basic` group with DataType + the browse ref in the `nodeId` address field
+   (`nsu=…;s=AlternatingBoolean`), not an identity key.
+5. **Calculation deploy + cycle gate** — a calc tag reading a Modbus RawPath deploys **202**;
+   a 2-cycle (`calc1/Engine/A`↔`calc1/Engine/B`) → **422** `[CalculationDependencyCycle] …
+   (members: calc1/Engine/A, calc1/Engine/B)`; clean redeploy 202, no crash loops (both
+   central nodes stable; only a deploy-reject WRN in the log).
+6. **Rename warning** — renaming `gate-modbus`→`gate-modbus-renamed` fired the warning modal
+   *"1 historized tag beneath this node will change its RawPath (historian tagname)…"*.
+7. **Retired routes** — `/clusters/{id}/drivers`, `…/new`, `…/new/{slug}`, `…/{id}` all
+   return **404**; `/raw` + `/uns` still 200.
+
+## Docs
+
+`docs/Raw.md` (new — the `/raw` authoring tree + endpoint split + CSV + Calculation +
+retirement note); `CLAUDE.md` AdminUI section updated; the Calculation mini-design remains the
+driver's authority.
@@ -0,0 +1,89 @@
+# v3 Batch 3 — UNS reference-only Equipment + `{{equip}}/<RefName>` reference-relative resolution
+
+Implements `docs/plans/2026-07-15-v3-batch3-uns-rework-plan.md` (WP1–WP4), executed via the
+`/v3-batch 3` coordinator: contracts-first fan-out, worktree-isolated Opus agents per wave, a
+code-reviewer pass + green build/test after each wave, then the non-negotiable 5-item live gate on
+docker-dev.
+
+## What landed
+
+- **Contracts** — `IEffectiveNameGuard` (authoring-time effective-name uniqueness seam; WP2 implements,
+  WP1 consumes).
+- **Wave A** (3 parallel agents):
+  - **WP1** — equipment **Tags** tab → `UnsTagReference` list (effective name / RawPath / inherited
+    DataType+AccessLevel / display-name override); new `AddReferenceModal` reusing `RawTree` in opt-in
+    `PickerMode` (multi-select tag leaves + device/tag-group "Select all tags below"), **cluster-scoped**
+    (structural + server-enforced `tag.cluster == equipment.cluster`); `UnsTreeService` reference CRUD;
+    consumes `IEffectiveNameGuard` in all colliding mutations; `ImportEquipmentModal`/`EquipmentInput`
+    dropped `DriverInstanceId`; deleted the retired equipment `TagModal`.
+  - **WP2** — `EffectiveNameGuard` (injectable, ordinal) + DI registration; verified the deploy-gate
+    `UnsEffectiveNameCollision` rule (already computes ref effective name as override-else-current-raw-name,
+    so it catches rename-induced collisions; ordinal; names both sources + equipment).
+  - **WP3** — `RawTreeService.BuildRenameWarningsAsync`: refined historized warning (only tags **without**
+    a `historianTagname` override) + UNS-referenced + **new** substring scan of every `Script.SourceCode`
+    for affected tags' OLD RawPaths (recomputed pre-save via `RawPathResolver`, ordinal).
+- **Wave B** (1 integration agent):
+  - **WP4** — `{{equip}}/<RefName>` reference-relative resolution. `EquipmentScriptPaths.DeriveEquipmentBase`
+    deleted; slash joint replaces the dot joint; new shared `EquipmentReferenceMap` (`equipmentId →
+    effectiveName → RawPath`) built identically at both compose seams (`AddressSpaceComposer` +
+    `DeploymentArtifact`, byte-parity). Unresolved-ref deploy error (`EquipReferenceUnresolved`) covering VT
+    scripts, SA predicates, and SA message-template tokens; authoring guard (`ValidateEquipTokenAsync`,
+    the Wave-A M1 fix); Monaco `{{equip}}/` completion of reference effective names + unresolved diagnostic
+    (`OTSCRIPT_EQUIPREF`), `EquipmentId` threaded request→model→JS.
+
+**Address space stays dark** (values light up in Batch 4). Full solution builds 0 errors; Commons **309**,
+Configuration **121**, AdminUI **659**, OpcUaServer **335/4-skip**, Runtime **361/42-skip** (the skips are
+the Batch-1 dark-address-space tests Batch 4 un-skips).
+
+## Reviewer findings fixed in-branch
+
+- **Wave A** — no HIGH. Verified: the register-AND-consume guard seam (prod DI injects the real guard; the
+  NoOp fallback only wins under `new` in tests; guard invoked in all 6 colliding mutations); cluster scoping
+  structural + server-enforced; Razor default `RawTree` byte-unchanged; WP3 pre-save RawPath recomputation.
+  L1 (misleading concurrency comment) fixed.
+- **Wave B** — no HIGH; byte-parity + production wiring confirmed. **M1** fixed: the editor⇔authoring⇔deploy
+  invariant now holds on the **ScriptedAlarm** surface too (SA predicate + message-template `{{equip}}` refs
+  validated at authoring, matching the deploy gate). **L3** fixed: parity test hardened (unresolved-ref-intact
+  + folder/tag-group RawPath ancestry). L1 already closed at the write path (empty override normalized→null).
+- **Deferred (documented follow-ups):** absolute-path Monaco completion still projects the raw leaf name, not
+  the RawPath (out of `{{equip}}` scope; `{{equip}}/` completion works) — rework `ScriptTagCatalog` to RawPaths
+  in Batch 4; a broken raw-topology-chain reference is deploy-accepted but compose-dropped (low reachability);
+  message-template `{{equip}}/X` is gate-validated but rendered/substituted only in Batch 4.
+
+## Live `/run` gate (docker-dev `:9200`, both central nodes rebuilt on Batch-3 code)
+
+Substrate: an Area→Line→Equipment seeded in MAIN, plus a SITE-A raw tag so cross-cluster exclusion is
+demonstrable. (Hand-seeded equipment surfaced the Batch-1 `EquipmentIdNotDerived` invariant — the canonical
+`EQ-<hash>` id was applied before the gate.)
+
+1. **Reference picker + list** — "+ Add reference" header *"The tree is scoped to the equipment's cluster"*;
+   only the **Main cluster** root shows (SITE-A/B absent — the seeded `SiteAOnly` tag unreachable); lazy
+   expansion; a device **"Select all tags below"** pulled tags across a collapsed group → **4 references in
+   one commit**. Rows show effective name / RawPath (incl. deep `opcua1/plc/OpcPlc/Telemetry/Basic/…`
+   ancestry) / DataType / Access / override. Set override "MainPressure" → effective name updated
+   `HR200 → MainPressure`, RawPath unchanged.
+2. **Collision** — *authoring:* setting a reference override to an existing VirtualTag's name → red banner
+   **"effective name 'GateVt' already used by VirtualTag 'VT-gatevt' in equipment '…'"** (not persisted).
+   *rename-induced:* renamed a raw tag so two references collide (allowed at rename) → deploy **422**
+   `[UnsEffectiveNameCollision] 2 UNS signals collide on effective name 'ImportedTag' … reference '…',
+   reference '…'`.
+3. **`{{equip}}` (editor ⇔ deploy)** — resolving `{{equip}}/MainPressure` deploys **202**; misspelled
+   `{{equip}}/MainPresure` deploys **422** `[EquipReferenceUnresolved] … has no reference named 'MainPresure'`.
+   Monaco: red squiggle + hover *"'{{equip}}/MainPresure' does not resolve — … no reference named
+   'MainPresure' … (OTSCRIPT_EQUIPREF)"*; typing `{{equip}}/` completes the four reference **effective**
+   names (AlternatingBoolean, ImportedTag, **MainPressure**, RandomSignedInt32).
+4. **Rename warning** — renaming a driver whose beneath-it tag is historized-without-override + UNS-referenced
+   + named in a script literal → **"Renamed — with warnings"** listing all three (historized fork,
+   UNS-referenced by 'gateequip', "2 scripts ('cval','gatevt') reference tags … by their raw paths"); renaming
+   an unrelated driver → **no warning dialog**. (Note: direct *tag* rename flows through `UpdateTagAsync`
+   which has no warnings surface — warnings fire on container renames affecting descendants; documented
+   follow-up if per-tag-rename warnings are wanted.)
+5. **Import without driver column** — the Import equipment CSV modal columns are `Name, MachineCode, UnsLineId`
+   (+ optional `ZTag, SAPID, Manufacturer, Model`); **no `DriverInstanceId`**.
+
+## Docs
+
+`docs/Uns.md` Tags section rewritten to the reference-only model; `docs/ScriptEditor.md` updated (WP4) to the
+slash/reference `{{equip}}` semantics; `CLAUDE.md` gains a v3 Batch 3 paragraph.
+
+https://claude.ai/code/session_01LVneM3eh1UtJxEisFXgmox
@@ -0,0 +1,115 @@
+# v3 Batch 4 — dual-namespace address space + raw-only runtime binding (= v3.0)
+
+Implements `docs/plans/2026-07-15-v3-batch4-address-space-plan.md` (B4-WP1–WP5), executed via the
+`/v3-batch 4` coordinator: contracts-first fan-out, worktree-isolated Opus agents per wave, a
+code-reviewer pass + green build/test after each wave, then the non-negotiable **7-leg v3.0 live gate**
+on docker-dev + Client.CLI. **This batch lights up the address space** — v3.0.
+
+## What landed
+
+- **Contracts** (`a1a56e22`) — two namespace URIs (`…/otopcua/raw`, `…/otopcua/uns`, replacing the single
+  `…/ns`), `V3NodeIds` (raw = `s=<RawPath>`, UNS = `s=<Area>/<Line>/<Equipment>/<EffectiveName>`), and the
+  `AddressSpaceRealm` (`Raw | Uns`) discriminator carried at every sink seam.
+- **Wave A** (2 agents ∥):
+  - **WP1** — composer/planner un-darkened: emit the **Raw** subtree (Folder→Driver→Device→TagGroup→Tag,
+    tags as `(realm=Raw, s=RawPath)`) + the **UNS** subtree (each `UnsTagReference` a Variable
+    `(realm=Uns, s=Area/Line/Equipment/EffectiveName)` carrying its backing RawPath + an `Organizes`
+    UNS→Raw ref); native-alarm plans at the **raw** tag (ConditionId=RawPath) carrying referencing-equipment
+    paths; per-realm planner diff (raw rename = remove+add Raw + re-point UNS); reactivated the Batch-1-skipped
+    `EquipmentNamespaceMaterializationTests`.
+  - **WP2** — node manager registers both namespaces; `AddressSpaceRealm` on every node-naming sink method
+    (maps keyed by ns-qualified NodeId so a Raw + UNS node sharing a bare `s=` id stay distinct; historized
+    UNS node registers the **same** tagname, mux single by RawPath); everything **forwarded through
+    `DeferredAddressSpaceSink`** + reflection guard extended (the forwarding trap). **M1 fix**: new
+    `AddReference` sink seam wiring the `Organizes` UNS→Raw edge bidirectionally (idempotent, missing-endpoint
+    no-op, forwarded + reflection-covered).
+- **Wave B** (1 agent — the delicate one):
+  - **WP3** — applier materializes both realms + wires the Organizes edge; `DriverHostActor` dual-NodeId
+    registration + single-source fan-out (drift-free — one publish → raw NodeId AND every referencing UNS
+    NodeId, identical value/quality/timestamp); write routing + failed-write revert through both NodeIds;
+    `EquipmentNodeIds` retired; transitional realm defaults removed from the sink surface. **Review fixes**:
+    **H1** realm-qualified `(realm, bareId)` write-routing key (a raw RawPath that coincidentally equals a UNS
+    path can no longer misroute a write); **M1** coherent-dormant discovery-injection guard; **M2** dual-node
+    self-correction tests; **L1** node-manager routing defaults removed (~180 call sites); byte-parity
+    round-trip test.
+- **Wave C** (2 agents ∥):
+  - **WP4** — multi-notifier native alarms: one condition at the raw tag, `AddNotifier`-fanned to the raw
+    device folder + every referencing equipment folder, **one `ReportEvent`** (exactly one Server-object copy —
+    proven by an over-the-wire event-delivery test), teardown symmetry (`RemoveNotifier(bidirectional:true)` on
+    rebuild/condition-removal/subtree-removal + reconcile), ack/confirm/shelve still on ConditionId=RawPath;
+    `AlarmTransitionEvent` + `/alerts` gain the referencing-equipment list. **Review fixes**: M1 event-delivery
+    test, M2 resolution-failure meter + composer↔applier path-agreement test, M3 reconcile, L1/L3.
+  - **WP5** — over-the-wire dual-namespace integration tests (`DualNamespaceAddressSpaceTests`) + 2-node
+    harness materialization round-trip; docs (`CLAUDE.md`, `docs/Uns.md`, `docs/ScriptEditor.md`,
+    `docs/Historian.md`, `docs/ScriptedAlarms.md`, `docs/AlarmTracking.md`).
+- **Coordinator seam-fix** — threaded `ReferencingEquipmentPaths` into `DriverHostActor.ForwardNativeAlarm`'s
+  `AlarmTransitionEvent` so `/alerts` chips populate in production (WP3-owned file WP4 couldn't edit).
+- **Live-gate bug fix** — the gate caught a genuine prod-inert defect: **Equipment VirtualTags never resolved
+  live** (a redeploy resets the VT's UNS node to `BadWaitingForInitialData`, but a surviving unchanged-plan
+  `VirtualTagActor` keeps its value-dedup state and suppresses the re-publish → the reset node stays Bad
+  forever with a static dependency). Fix: `ReassertValue` on apply re-emits the last value after the node
+  reset. Regression test fail-before/pass-after; live-verified Good. (Reviewer follow-ups: reassert skips
+  historian re-record (M1); scripted-alarm redeploy recovery (M2); comment (LOW-3).)
+
+## Reviewer verdict per wave
+
+No HIGH survived any wave. Wave A: forwarding trap verified solid (DispatchProxy guard catches unforwarded
+methods), collision-free ns-qualified keying, planner raw-rename-repoints-UNS holds; M1 (Organizes seam) fixed.
+Wave B: **H1** write-route realm collision fixed with a regression test; M1/M2/L1 fixed. Wave C: single-ReportEvent
+ teardown symmetry + forwarding trap all confirmed; M1/M2/M3/L1/L3 fixed. VT-fix review: ordering confirmed real,
+dedup/02-S13 semantics intact; M1/M2/LOW-3 closed.
+
+## v3.0 live gate (docker-dev `:9200` / `opc.tcp://:4840`+`:4841`, both centrals rebuilt on Batch-4 code)
+
+1. **Browse both namespaces** — `ns=2` Raw tree (`pymodbus/plc/HR200`, `s=<RawPath>`) + `ns=3` UNS tree
+   (`gatearea/gateline/gateequip/MainPressure`, effective names); both materialize `failed=0`.
+2. **Single-source fan-out** — `MainPressure` (UNS) = `HR200` (Raw) = **1234**, identical value AND timestamp;
+   Calculation tag `Cval` computes (=1235); the `{{equip}}/MainPressure` VirtualTag reads Good (post-fix).
+3. **Writes** — write **4242** via the UNS NodeId → read-back **4242** via the raw NodeId; write **777** via the
+   raw NodeId; `opc-readonly` rejected **0x801F0000** on the UNS NodeId (role gating symmetric). Failed-write
+   dual-node revert is unit-covered (`exception_injector` fixture not provisioned on this rig).
+4. **History** — HistoryRead via the raw NodeId and the UNS NodeId both return **GoodNoData** under the same
+   historian tagname (Null source — no gateway on docker-dev); provisioning tally `dispatched=1 … failed=0`.
+5. **Alarms (multi-notifier)** — the native alarm materialized as a Part 9 **AlarmCondition** at the raw tag
+   (ConditionId = RawPath); the **equipment folder** accepts an alarm subscription + ConditionRefresh, proving
+   it is a live event-notifier wired to the raw condition; the Server object likewise. The transition delivery
+   (exactly-one Server copy + delivery at both notifiers + ack) is covered by the over-the-wire
+   `NativeAlarmMultiNotifierEventDeliveryTests` — docker-dev has no `IAlarmSource` driver (only Galaxy is one)
+   so a live transition can't be tripped on the rig.
+6. **Rename cascade** — renamed `HR200`→`HR200X` + deployed: old raw NodeId gone, new present; the UNS
+   reference `MainPressure` follows automatically; the `{{equip}}` VirtualTag keeps working and tracks the
+   renamed tag live (3610→3611 Good); the **absolute** RawPath script literal (`Cval`) now fails **Bad
+   0x80000000**. (Caveat: a raw-tag rename needs a node recreate/restart to hot-rebind the renamed tag's live
+   driver value — the pre-existing deploy-THEN-recreate pattern for structural edits.)
+7. **Redundancy** — ServiceLevel split **central-1 = 250 / central-2 = 240** (both Good) — the Primary/Secondary
+   differentiation is intact with the second namespace present; single-emit-per-condition is unit-covered (the
+   alarm-emit gate is Primary-only).
+
+## Tests
+
+Full solution builds **0 errors**. Commons 306, Configuration 121, OpcUaServer 375/4-skip (+ OpcUaServer.IntegrationTests
+dual-namespace + event-delivery), Runtime 377 (+ VT reassert regression), AdminUI 659, Host.IntegrationTests green
+(the pre-existing Batch-2 `Calculation`-probe stale test fixed here). The remaining Runtime skips are legacy
+`EquipmentTags`-model dark tests + the dormant discovery-injection scenarios (accurate skip reasons).
+
+## Documented follow-ups (non-blocking)
+
+- **Scripted-alarm redeploy recovery (CONFIRMED pre-existing bug, deferred — deserves its own careful fix).**
+  The scripted-alarm Part 9 condition node has the same redeploy-reset race the VT `ReassertValue` fix closed:
+  `RebuildAddressSpace` clears `_alarmConditions` and `MaterialiseScriptedAlarms` recreates each condition
+  fresh/normal, but `ScriptedAlarmEngine.LoadAsync` reloads from the persisted state and yields
+  `EmissionKind.None` for a still-active condition (dropped by `OnEngineEmission`), so an **active scripted
+  alarm with static dependencies under-reports as normal after a full-rebuild deploy until its next real
+  transition** (the known "snapshot-is-one-shot / restart-to-re-deliver" gotcha — NOT a Batch-4 regression).
+  Deferred because the fix is a Core-engine emission-contract change carrying **double-alarm-history risk**
+  (a naive re-emit would append a duplicate AVEVA/historian row per deploy — the alarm analogue of the VT M1
+  historian issue). Proposed shape: a host-driven, node-only `AlarmStateUpdate` re-assert in `OnAlarmsLoaded`
+  (same safe post-materialise ordering as the VT fix), reusing `_engine.GetState(alarmId)` + `LoadedAlarmIds`,
+  **never touching the `alerts` topic**.
+- Raw-tag rename hot-rebind of the renamed tag's live value without a recreate (today: deploy-THEN-recreate).
+- Absolute-path Monaco completion → RawPath (from Batch 3; the `{{equip}}/` completion works).
+- Cross-repo (post-merge): ScadaBridge Data-Connection-Layer NodeId/namespace cutover (raw `s=<RawPath>` /
+  UNS `s=<Area>/<Line>/<Equipment>/<EffectiveName>`, retired `EquipmentNodeIds`) + the umbrella index
+  `../scadaproj/CLAUDE.md` OtOpcUa entry.
+
+https://claude.ai/code/session_01LVneM3eh1UtJxEisFXgmox
@@ -0,0 +1,187 @@
+# Alarm condition Quality (issue #477) — design
+
+**Status:** implemented (L1+L2) · **Date:** 2026-07-17 · **Issue:** #477 (follow-up chain #473 → #475 → #477)
+**Scope decision:** Layer 1 + Layer 2, Bad-direct, annotate-only. Layer 3 (scripted worst-of-input) deferred → **#478**.
+
+## Problem
+
+`AlarmConditionState.Quality` is never assigned anywhere in `src/` — neither by
+`OtOpcUaNodeManager.MaterialiseAlarmCondition` nor by the `WriteAlarmCondition` transition path.
+Because `StatusCodes.Good == 0x00000000`, `default(StatusCode)` **is** `Good`, so the field is
+*accidentally valid* — clients parse it, but it reports **`Good` unconditionally regardless of the
+backing tag's real quality**.
+
+This is a wrong-*value* bug, not the null-value bug class of #473/#475. Part 9 defines
+`ConditionType.Quality` as "the quality of the Condition's source data". OT impact: when a native
+alarm's device goes offline (comms lost) the condition still reports `Quality = Good`, so an operator
+(or an HMI bucketing on `IsGood`) cannot distinguish *"genuinely not active"* from *"we have lost
+contact and do not know"*.
+
+## Why it isn't a 2-line default (confirmed by code)
+
+1. **Alarm-bearing raw tags have no value variable.** `AddressSpaceApplier` materialises a raw tag as
+   *either* a condition node (`tag.Alarm is not null`) *or* a value variable (`else`) — never both,
+   since they'd share the same `s=<RawPath>` NodeId. So `WriteValue` (the only path carrying
+   `OpcUaQuality`) is never invoked for an alarm node. Quality has nowhere to land today.
+2. **The alarm channel is quality-blind.** `AlarmEventArgs` (driver → host) and `AlarmConditionSnapshot`
+   (host → SDK sink) both carry no quality field.
+3. **On comms-loss the alarm feed goes silent.** `DriverInstanceActor` on `DisconnectObserved` detaches
+   the alarm subscription and re-enters `Reconnecting` — no transition event ever arrives to carry Bad.
+   So the "device offline" signal must come from **driver connectivity**, independently of alarm
+   transitions.
+
+## Decisions (the issue's open questions)
+
+| # | Question | Decision | Rationale |
+|---|----------|----------|-----------|
+| 1 | Does an alarm tag get quality today? | No | Confirmed above — new plumbing required. |
+| 2 | Direct status code vs. policy map | **Direct Bad** on comms-loss; Good on reconnect | Matches how a value variable would read; unambiguous for `IsGood` bucketing. |
+| 3 | Does Bad also suppress transitions / touch Retain? | **No — annotate only** | A comms-lost *active* condition must stay active + retained. Silently clearing an active alarm on comms-loss is the unsafe direction. Quality is a pure annotation; the Active/Ack/Retain state machine is untouched. |
+| 4 | Scripted alarms: worst-of-inputs quality? | **Deferred (Layer 3)** | Scripted conditions stay `Good`. Filed as a follow-up issue. |
+
+## Architecture — reuse the existing publish path, add no sink method
+
+The key move: **do not add a new `IOpcUaAddressSpaceSink` method.** A new sink-interface surface would
+have to be forwarded through `DeferredAddressSpaceSink` or it is inert on driver hosts (the F10b
+prod-inertness trap). Instead the `NativeAlarmProjector` becomes the single owner of per-condition
+state *and* quality, and a connectivity change re-projects the *last* snapshot with a swapped quality
+through the **existing** `AlarmStateUpdate → OpcUaPublishActor → WriteAlarmCondition` path.
+
+### Layer 1 — make Quality a real, plumbed field
+
+- `AlarmConditionSnapshot` (Commons) gains `OpcUaQuality Quality` (last positional param, default
+  `OpcUaQuality.Good` so scripted callers and existing tests keep compiling; Commons already knows
+  `OpcUaQuality` via `IOpcUaAddressSpaceSink`).
+- `MaterialiseAlarmCondition` sets `alarm.Quality.Value` at build time:
+  **native → `BadWaitingForInitialData`** (honest until connectivity confirms Good, matching the
+  value-variable "waiting for initial data" convention), **scripted → `Good`** (script-computed, always
+  live in this scope).
+- `WriteAlarmCondition` projects `StatusFromQuality(state.Quality)` onto `condition.Quality.Value`
+  (+ `SourceTimestamp`).
+- The delta-gate (`AlarmConditionDelta` / `ReadConditionDelta` / `ToConditionDelta`) gains a `Quality`
+  member, so a Good→Bad bucket change is a genuine delta and **fires a Part 9 condition event**.
+
+### Layer 2 — drive native quality from driver connectivity
+
+- `DriverInstanceActor`: new `public sealed record ConnectivityChanged(string DriverInstanceId, bool Connected)`.
+  `Context.Parent.Tell` it on `Become(Connected)` entry (`true`) and on the transitions into
+  `Reconnecting` (`DisconnectObserved` / `ForceReconnect`) (`false`). Fire-and-forget, mirrors
+  `DeltaApplied`.
+- `NativeAlarmProjector`: per-node state becomes `(bool Active, bool Acked, OpcUaQuality Quality)`.
+  `Project(transition)` preserves the current quality; new `ProjectQuality(nodeId, quality)` preserves
+  Active/Acked and swaps only the quality, returning a full snapshot.
+- `DriverHostActor`: `Receive<ConnectivityChanged>` iterates `_alarmNodeIdByDriverRef` for that driver
+  instance and Tells one `AlarmStateUpdate` per condition with the re-projected snapshot
+  (`connected ? Good : Bad`). **Ungated** — both redundancy nodes track their own driver's comms, matching
+  the existing "condition write stays ungated (Secondary keeps its address space warm)" rule.
+  **No `/alerts` row** for a quality-only change — driver health already has its own status/alerts surface
+  via `IDriverHealthPublisher`; a row here would be alarm-fatigue.
+
+Scripted alarms are unaffected: they are not driver instances, receive no `ConnectivityChanged`, and
+their snapshot quality stays `Good`.
+
+## Files
+
+**Layer 1**
+- `src/Core/ZB.MOM.WW.OtOpcUa.Commons/OpcUa/AlarmConditionSnapshot.cs`
+- `src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/OtOpcUaNodeManager.cs` (`MaterialiseAlarmCondition`,
+  `WriteAlarmCondition`, `AlarmConditionDelta`/`ReadConditionDelta`/`ToConditionDelta`)
+- `src/Server/ZB.MOM.WW.OtOpcUa.Runtime/ScriptedAlarms/ScriptedAlarmHostActor.cs` (`ToSnapshot` — Quality=Good, or rely on default)
+
+**Layer 2**
+- `src/Server/ZB.MOM.WW.OtOpcUa.Runtime/Drivers/DriverInstanceActor.cs`
+- `src/Server/ZB.MOM.WW.OtOpcUa.Runtime/Drivers/NativeAlarmProjector.cs`
+- `src/Server/ZB.MOM.WW.OtOpcUa.Runtime/Drivers/DriverHostActor.cs`
+
+## Tests (TDD, RED-first)
+
+1. **Wire-level (the issue's suggested guard)** — extend `NativeAlarmEventIdentityFieldDeliveryTests`
+   (OpcUaServer.IntegrationTests): active alarm → event `Quality.IsGood`; driver disconnect → condition
+   event `Quality.IsGood == false`; reconnect → Good. Verify RED against pre-fix.
+2. **Node-level** — `NodeManagerAlarmSourceFieldsTests`: materialise sets Quality (native
+   `BadWaitingForInitialData`, scripted `Good`); `WriteAlarmCondition` projects snapshot quality and
+   fires on a quality-bucket change only.
+3. **`NativeAlarmProjector`** unit: `ProjectQuality` keeps Active/Acked + swaps quality; `Project`
+   preserves quality.
+4. **`DriverInstanceActor`**: `Connected` entry Tells `ConnectivityChanged(true)`; `DisconnectObserved`
+   Tells `ConnectivityChanged(false)`.
+5. **`DriverHostActor`**: `ConnectivityChanged(false)` pushes a Bad-quality `AlarmStateUpdate` to every
+   condition of that driver instance.
+
+## Deferred / notes
+
+- **Layer 3** (scripted worst-of-input quality) → **Gitea #478**.
+- **Implementation note:** L2 uses a **dedicated `IOpcUaAddressSpaceSink.WriteAlarmQuality`** path (not a
+  full-snapshot re-projection). Rationale: a connectivity change must set *only* Quality; re-projecting a full
+  snapshot would clobber a cold condition's severity/message and can't annotate a condition that never fired a
+  transition. The new sink method is forwarded through `DeferredAddressSpaceSink` (the F10b inertness trap) —
+  auto-verified by `DeferredSinkForwardingReflectionTests` (reflection guard) + its realm-discriminator guard.
+- **Test-harness note:** the new `DriverInstanceActor → parent` `ConnectivityChanged` Tell polluted existing
+  parent-`TestProbe` assertions in 3 `DriverInstanceActor*Tests` files; those tests now
+  `parent.IgnoreMessages(m => m is ConnectivityChanged)` since they assert on data/alarm/discovery forwards,
+  not connectivity.
+- `Bad_NoCommunication` vs generic `Bad`: v1 maps `OpcUaQuality.Bad → StatusCodes.Bad`; refining
+  `StatusFromQuality` to emit `BadNoCommunication` for the comms-loss case is a one-line nicety, noted in
+  the issue.
+- `docs/AlarmTracking.md` §"Condition event identity fields" gains a Quality subsection (Good/Bad
+  semantics, annotation-not-state-change, quality-bucket change fires an event).
+
+## Layer 3 — scripted worst-of-input quality (Gitea #478, implemented 2026-07-17)
+
+**Problem.** A scripted alarm is computed from one or more input tags. Its condition should report the
+**worst** quality of those inputs ("can I trust this condition's state?"), not the hardcoded `Good` Layer 1
+left at `ScriptedAlarmHostActor.ToSnapshot`.
+
+**Two blockers discovered in the live path (both silently discard quality):**
+1. `DependencyMuxActor.OnAttributeValuePublished` builds `VirtualTagActor.DependencyValueChanged` **without**
+   the `AttributeValuePublished.Quality` it already carries.
+2. `ScriptedAlarmHostActor.OnDependencyChanged` pushes each mux value into the engine's upstream with a
+   **hardcoded `0u` (Good)** StatusCode.
+So even a `Bad` driver value reached the scripted engine as Good — Layer 3 has to plumb quality first.
+
+**Design (mirrors Layer 2's native OT semantic through the scripted channel):**
+- **Plumb quality end-to-end.** `DependencyValueChanged` gains `OpcUaQuality Quality` (defaulted `Good`, so the
+  virtual-tag engine's calls are unchanged); the mux forwards `msg.Quality`; `OnDependencyChanged` maps it to a
+  StatusCode (`Good→0`, `Uncertain→0x40000000`, `Bad→0x80000000`) on the pushed `DataValueSnapshot`.
+- **Engine computes the worst input quality** each evaluation (over the refilled read cache, **before** the
+  `AreInputsReady` short-circuit so a `Bad` input is still observed) and carries it as
+  `ScriptedAlarmEvent.WorstInputStatusCode` (a raw `uint` StatusCode — `Core.ScriptedAlarms` doesn't reference
+  Commons, so it stays in the engine's existing StatusCode vocabulary; the host maps it to `OpcUaQuality`).
+- **Transitions carry the current worst quality** → `ToSnapshot` projects it (no clobber-back-to-Good when a
+  transition fires while an input is `Uncertain`).
+- **Quality-only changes emit out of band.** A `Bad` input freezes the condition (`AreInputsReady` returns
+  false → no transition), exactly like a comms-lost native driver — so quality can't ride a transition. The
+  engine tracks the last worst-quality **bucket** per alarm and, when the bucket changes with **no** transition
+  emission, emits a new `EmissionKind.QualityChanged` event. The host routes that to the **existing** Layer 2
+  `OpcUaPublishActor.AlarmQualityUpdate → IOpcUaAddressSpaceSink.WriteAlarmQuality` path (sets ONLY Quality,
+  one Part 9 event on a bucket change, **no `/alerts` row**, no historian write). No new sink surface.
+- **`ScriptedAlarmSource` (the `IAlarmSource` fan-out adapter) skips `QualityChanged`** — quality is delivered
+  through the dedicated node path, never as a phantom `AlarmEventArgs` (which would materialize/historize a
+  native condition).
+
+**Files (Layer 3):**
+- `src/Core/ZB.MOM.WW.OtOpcUa.Core.ScriptedAlarms/Part9StateMachine.cs` — `EmissionKind.QualityChanged`.
+- `src/Core/ZB.MOM.WW.OtOpcUa.Core.ScriptedAlarms/ScriptedAlarmEngine.cs` — worst-of-input, bucket tracking,
+  `WorstInputStatusCode` on the event, quality-only emission.
+- `src/Core/ZB.MOM.WW.OtOpcUa.Core.ScriptedAlarms/ScriptedAlarmSource.cs` — skip `QualityChanged`.
+- `src/Server/ZB.MOM.WW.OtOpcUa.Runtime/VirtualTags/VirtualTagActor.cs` — `DependencyValueChanged.Quality`.
+- `src/Server/ZB.MOM.WW.OtOpcUa.Runtime/VirtualTags/DependencyMuxActor.cs` — forward `msg.Quality`.
+- `src/Server/ZB.MOM.WW.OtOpcUa.Runtime/ScriptedAlarms/ScriptedAlarmHostActor.cs` — push real quality;
+  `ToSnapshot` maps `WorstInputStatusCode`; `OnEngineEmission` routes `QualityChanged → AlarmQualityUpdate`.
+
+**Tests (RED-first):** engine — transition carries `Uncertain` worst; `Bad` input with no transition emits
+`QualityChanged(Bad)`; restore emits `QualityChanged(Good)`; no spurious emit when the bucket is unchanged.
+`ScriptedAlarmSource` — `QualityChanged` raises no `OnAlarmEvent`. Mux — `DependencyValueChanged` carries the
+published quality. Host — `Bad` dependency → `AlarmQualityUpdate(Bad)`, no `/alerts` publish; `ToSnapshot`
+maps the event's worst quality.
+
+**Coverage boundary → Layer 4 (#481).** L3 covers inputs whose driver **publishes a Bad/Uncertain-status
+data change** (the mux quality path). It does **not** cover a driver **comms loss**: a poll driver
+(Modbus/S7) whose device goes unreachable emits only `ConnectivityChanged` and goes silent on the value feed
+(`DriverInstanceActor.Reconnecting`), so the scripted engine keeps the last-known Good value and the
+condition stays Good — the same silent-feed problem native solved in L2, but native's `OnDriverConnectivityChanged`
+bridge fans only to **native** condition nodes (`_alarmNodeIdByDriverRef`), not into the mux the scripted
+engine reads. Bridging connectivity into scripted inputs — plus resolving the null-value/cold-start
+asymmetry (a runtime `Bad` with a null value is currently indistinguishable from cold start and contributes
+`Good`) and its ripple into virtual-tag quality — is **Gitea #481 (Layer 4)**. Found by the post-implementation
+code review; the code as shipped faithfully implements #478's written scope (mux-delivered input quality).
@@ -0,0 +1,706 @@
+# OtOpcUa LocalDb Adoption — Phase 1 Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers-extended-cc:executing-plans to implement this plan task-by-task.
+>
+> **Execution model:** This plan is optimized for **Claude Opus** agents (`claude --model opus`).
+> Dispatch implementer subagents on Opus for every task classified `high-risk`; `small`/`trivial`
+> tasks may use Sonnet. Work on branch **`feat/localdb-phase1`** in this repo (`~/Desktop/OtOpcUa`,
+> remote `lmxopcua`). Do NOT merge to `master` as part of this plan — stop at the DoD task and
+> report.
+>
+> **Design authority:** `~/Desktop/scadaproj/docs/plans/2026-07-20-otopcua-localdb-design.md`.
+> Read it before Task 0. The reference adoption is ScadaBridge (merged PR #23) — when in doubt,
+> mirror `~/Desktop/ScadaBridge` (files named per task below).
+
+**Goal:** Give every driver-role OtOpcUa node a consolidated `ZB.MOM.WW.LocalDb` database that caches
+the deployed-configuration artifact (chunked), boots from that cache when central SQL Server is
+unreachable, and optionally replicates it to the node's redundant pair peer over the library's gRPC
+sync (default-OFF, fail-closed bearer auth).
+
+**Architecture:** `AddZbLocalDb`/`AddZbLocalDbReplication` wired in a new `LocalDbRegistration`
+(mirroring `SecretsRegistration`), DDL + `RegisterReplicated` in `LocalDbSetup.OnReady`, a dedicated
+Kestrel h2c listener for `MapZbLocalDbSync` gated on `LocalDb:SyncListenPort`, a consumer-supplied
+fail-closed bearer interceptor, and an `IDeploymentArtifactCache` seam written by `DriverHostActor`
+after each successful apply and read as a boot fallback. The dormant LiteDB LocalCache subsystem is
+deleted as superseded.
+
+**Tech stack:** .NET 10, `ZB.MOM.WW.LocalDb`/`.Replication`/`.Contracts` **0.1.1** (Gitea feed),
+`Grpc.AspNetCore` 2.76.0, Akka.NET (existing), xunit.v3 (Host.IntegrationTests) + xunit2 TestKit
+(actor tests).
+
+**Hard rules (from the ScadaBridge adoption — violating any of these is a defect):**
+1. Order inside `OnReady` is load-bearing: **DDL → `RegisterReplicated` → writes**. Rows written
+   before registration are never captured or snapshotted — silently, forever.
+2. No autoincrement PKs, no BLOB columns in replicated tables.
+3. The library's passive sync endpoint verifies **no** ApiKey — the host interceptor is the only
+   auth, and it must be fail-closed (no key configured ⇒ deny everything).
+4. `ILocalDb.CreateConnection()` returns an **already-open**, pragma-configured connection with the
+   `zb_hlc_next()` UDF. Never call `Open()` on it. There is **no in-memory mode** — tests use temp
+   files + `SqliteConnection.ClearAllPools()` before delete.
+5. `Grpc.Core.Testing` does not exist on grpc-dotnet — hand-roll fake `ServerCallContext`s.
+6. Explicit Kestrel `Listen*` calls make Kestrel **ignore `ASPNETCORE_URLS`** — when adding the sync
+   listener you must re-bind the existing HTTP port in the same block, and verify it on the rig.
+7. Never run host `sqlite3` against a live bind-mounted WAL DB (copy the `db`/`-wal`/`-shm` triplet
+   with `cp` instead). `aspnet:10.0` containers have no `curl` — use a
+   `curlimages/curl` sidecar with `--network container:<name>`.
+
+---
+
+### Task 0: Preflight + recon (produces `docs/plans/2026-07-20-localdb-phase1-recon.md`)
+
+**Classification:** standard
+**Estimated implement time:** ~5 min
+**Parallelizable with:** none (everything downstream consumes its findings)
+
+**Files:**
+- Create: `docs/plans/2026-07-20-localdb-phase1-recon.md`
+- Read-only: `src/Server/ZB.MOM.WW.OtOpcUa.Runtime/Drivers/DriverHostActor.cs`,
+  `src/Server/ZB.MOM.WW.OtOpcUa.Runtime/Drivers/DeploymentArtifact.cs`,
+  `src/Server/ZB.MOM.WW.OtOpcUa.Host/Program.cs`,
+  `src/Server/ZB.MOM.WW.OtOpcUa.Host/Configuration/SecretsRegistration.cs`,
+  `Directory.Packages.props`, `docker-dev/docker-compose.yml`,
+  the observability registration (`AddOtOpcUaObservability` implementation),
+  `src/Core/ZB.MOM.WW.OtOpcUa.Configuration/LocalCache/*`
+
+**Step 1: Verify the feed packages restore.**
+
+Run:
+```bash
+cd ~/Desktop/OtOpcUa && dotnet package search ZB.MOM.WW.LocalDb --source dohertj2-gitea --format json | head -50
+```
+Expected: `ZB.MOM.WW.LocalDb`, `.Replication`, `.Contracts` at `0.1.1`. If absent → STOP, report.
+
+**Step 2: Map and record, with `file:line` citations, each of:**
+1. **Deploy fetch path:** where `DriverHostActor` loads `Deployment.ArtifactBlob` (the
+   `_dbFactory.CreateDbContext()` sites, ~L1472/1543), the artifact's runtime type
+   (`DeploymentArtifact` — how it's deserialized from the blob), the type/format of
+   `DeploymentId` and `RevisionHash`, and where a successful apply completes (the point after
+   which the cache write belongs).
+2. **Cold-boot path:** what the actor does at startup before any `DispatchDeployment` arrives —
+   does it query central SQL for the current deployment? Where does the failure path land
+   (the `Stale` state, `DbHealthProbeActor` interaction, L1345 dispatch-ignore)? Identify the
+   exact seam where "central fetch failed at boot" is known — that is where the cache fallback goes.
+3. **Cluster identity:** how a driver node knows its `ClusterId` (config key / `ClusterNode` row /
+   `IClusterRoleInfo`) — the cache is keyed by it.
+4. **DriverHostActor construction:** how its dependencies are injected
+   (`WithOtOpcUaRuntimeActors`, `Props` wiring) so `IDeploymentArtifactCache` can be threaded in.
+   ⚠ `Props.Create` builds an expression tree — adding a parameter silently rebinds
+   out-of-position named args at call sites; list every construction site.
+5. **Telemetry allowlist:** does `AddOtOpcUaObservability` restrict meters
+   (`ZbTelemetryOptions.Meters` or equivalent)? If yes, record where the list lives.
+6. **Kestrel/URLs:** confirm the Host binds via `ASPNETCORE_URLS=http://+:9000` with no
+   `ConfigureKestrel` calls; record any existing `builder.WebHost` usage.
+7. **LiteDB LocalCache:** confirm (grep) that nothing outside
+   `src/Core/ZB.MOM.WW.OtOpcUa.Configuration/LocalCache/` and its tests references
+   `ILocalConfigCache`/`GenerationSealedCache`/`ResilientConfigReader`/`LiteDB`.
+8. **docker-dev volumes:** whether nodes have a writable data volume; record what `LocalDb:Path`
+   should be per node and how env vars are passed (`Cluster__*` style double-underscore).
+
+**Step 3: STOP conditions — halt the plan and report instead of improvising if:**
+- the artifact apply path cannot be given a post-apply hook without restructuring the actor;
+- `DeploymentId`/cluster identity are not stable strings/GUIDs;
+- LiteDB LocalCache turns out to be referenced by live code.
+
+**Step 4: Commit.**
+```bash
+git add docs/plans/2026-07-20-localdb-phase1-recon.md
+git commit -m "docs(localdb): phase-1 recon findings"
+```
+
+---
+
+### Task 1: Package references and pins
+
+**Classification:** small
+**Estimated implement time:** ~3 min
+**Parallelizable with:** none (all code tasks build on it)
+
+**Files:**
+- Modify: `Directory.Packages.props`
+- Modify: `src/Server/ZB.MOM.WW.OtOpcUa.Host/ZB.MOM.WW.OtOpcUa.Host.csproj`
+- Modify: `src/Server/ZB.MOM.WW.OtOpcUa.Runtime/ZB.MOM.WW.OtOpcUa.Runtime.csproj`
+
+**Step 1:** Add to `Directory.Packages.props` (versions exact):
+```xml
+<PackageVersion Include="ZB.MOM.WW.LocalDb" Version="0.1.1" />
+<PackageVersion Include="ZB.MOM.WW.LocalDb.Replication" Version="0.1.1" />
+<PackageVersion Include="Grpc.AspNetCore" Version="2.76.0" />
+```
+Check the existing `Grpc.Net.Client`/`Grpc.Core.Api` are already ≥ 2.76.0 and
+`Google.Protobuf` ≥ 3.34.1 (the LocalDb.Replication nuspec floors); raise if not. Confirm a
+`SQLitePCLRaw` pin ≥ 2.1.12 exists for the transitive `Microsoft.Data.Sqlite` chain (the family
+advisory GHSA-2m69-gcr7-jv3q); Core.AlarmHistorian already pins `bundle_e_sqlite3` 2.1.12 — add
+`SQLitePCLRaw.lib.e_sqlite3` 2.1.12 as an explicit reference in the Host if the audit flags it.
+
+**Step 2:** Host csproj: `ZB.MOM.WW.LocalDb`, `ZB.MOM.WW.LocalDb.Replication`, `Grpc.AspNetCore`.
+Runtime csproj: `ZB.MOM.WW.LocalDb` only (it needs `ILocalDb`, not the sync engine).
+
+**Step 3:** `dotnet build ZB.MOM.WW.OtOpcUa.slnx` → 0 warnings/errors (repo builds warnings-as-errors).
+
+**Step 4: Commit.** `git commit -m "build(localdb): reference ZB.MOM.WW.LocalDb 0.1.1 + Grpc.AspNetCore"`
+
+---
+
+### Task 2: Schema + `LocalDbSetup.OnReady` + registration tests
+
+**Classification:** standard
+**Estimated implement time:** ~5 min
+**Parallelizable with:** Task 3
+
+**Files:**
+- Create: `src/Server/ZB.MOM.WW.OtOpcUa.Runtime/Deployment/DeploymentCacheSchema.cs`
+- Create: `src/Server/ZB.MOM.WW.OtOpcUa.Host/Configuration/LocalDbSetup.cs`
+- Test: `tests/Server/ZB.MOM.WW.OtOpcUa.Host.Tests/LocalDbSetupTests.cs` (create the test project
+  reference layout to match neighboring Host unit tests; if Host has no unit-test project, place in
+  the closest existing one and note the deviation)
+
+**Step 1: Write the failing tests first** — using a real temp-file `ILocalDb` (build it via
+`new ServiceCollection().AddZbLocalDb(config, LocalDbSetup.OnReady)` with `LocalDb:Path` pointed at
+a temp file; dispose + `SqliteConnection.ClearAllPools()` in cleanup):
+- `OnReady_RegistersExactlyTheTwoDeploymentTables` — `db.ReplicatedTables.Keys` ordinal-sorted
+  equals `["deployment_artifacts", "deployment_pointer"]` (assert BOTH directions: no fewer, no more).
+- `DeploymentArtifacts_PkIsDeploymentIdPlusChunkIndex` and `DeploymentPointer_PkIsClusterId`
+  (pin `ReplicatedTable.PkColumns`).
+- `RowsWrittenAfterOnReady_EnterTheOplog` — insert a row, assert `SELECT COUNT(*) FROM __localdb_oplog` ≥ 1
+  (pins the DDL→register ordering; this is the assertion that catches a silently-broken CDC).
+
+**Step 2: Run tests, watch them fail** (types don't exist yet).
+
+**Step 3: Implement.** `DeploymentCacheSchema` depends only on `Microsoft.Data.Sqlite` (the
+ScadaBridge `*Schema.Apply` pattern — self-sufficient for direct construction in tests):
+
+```csharp
+namespace ZB.MOM.WW.OtOpcUa.Runtime.Deployment;
+
+public static class DeploymentCacheSchema
+{
+    public static void Apply(SqliteConnection connection)
+    {
+        using var cmd = connection.CreateCommand();
+        cmd.CommandText = """
+            CREATE TABLE IF NOT EXISTS deployment_artifacts (
+                deployment_id   TEXT    NOT NULL,
+                chunk_index     INTEGER NOT NULL,
+                cluster_id      TEXT    NOT NULL,
+                revision_hash   TEXT    NOT NULL,
+                chunk_count     INTEGER NOT NULL,
+                chunk_base64    TEXT    NOT NULL,
+                cached_at_utc   TEXT    NOT NULL,
+                PRIMARY KEY (deployment_id, chunk_index)
+            );
+            CREATE TABLE IF NOT EXISTS deployment_pointer (
+                cluster_id        TEXT NOT NULL PRIMARY KEY,
+                deployment_id     TEXT NOT NULL,
+                revision_hash     TEXT NOT NULL,
+                artifact_sha256   TEXT NOT NULL,
+                applied_at_utc    TEXT NOT NULL
+            );
+            """;
+        cmd.ExecuteNonQuery();
+    }
+}
+```
+
+`LocalDbSetup` (Host):
+```csharp
+namespace ZB.MOM.WW.OtOpcUa.Host.Configuration;
+
+internal static class LocalDbSetup
+{
+    // ORDER IS LOAD-BEARING: DDL, then RegisterReplicated, then (nothing else in Phase 1).
+    // Rows written before RegisterReplicated are invisible to the peer forever, silently.
+    public static void OnReady(ILocalDb db)
+    {
+        using var connection = db.CreateConnection(); // already open — do NOT call Open()
+        DeploymentCacheSchema.Apply(connection);
+        db.RegisterReplicated("deployment_artifacts");
+        db.RegisterReplicated("deployment_pointer");
+    }
+}
+```
+
+**Step 4:** `dotnet test --filter "FullyQualifiedName~LocalDbSetupTests"` → PASS.
+
+**Step 5: Commit.** `git commit -m "feat(localdb): deployment-cache schema + OnReady registration"`
+
+---
+
+### Task 3: Fail-closed sync auth interceptor + tests
+
+**Classification:** standard
+**Estimated implement time:** ~4 min
+**Parallelizable with:** Task 2
+
+**Files:**
+- Create: `src/Server/ZB.MOM.WW.OtOpcUa.Host/Configuration/LocalDbSyncAuthInterceptor.cs`
+- Test: `tests/Server/ZB.MOM.WW.OtOpcUa.Host.Tests/LocalDbSyncAuthInterceptorTests.cs`
+
+Port ScadaBridge's `src/ZB.MOM.WW.ScadaBridge.Host/LocalDbSyncAuthInterceptor.cs` (read it first;
+keep behavior identical, adjust namespace only). Semantics to preserve exactly:
+- `ServicePrefix = "/localdb_sync.v1.LocalDbSync/"`; any other method path passes through untouched.
+- Expected token from `IOptions<ReplicationOptions>.Value.ApiKey`.
+- **Fail-closed:** null/empty configured key ⇒ `RpcException(new Status(StatusCode.PermissionDenied, ...))`
+  for every sync call. Missing/mismatched bearer ⇒ same.
+- `CryptographicOperations.FixedTimeEquals` over UTF-8 bytes; header `authorization`,
+  case-insensitive, `"Bearer "` prefix. Override all four server handler kinds.
+
+**Tests** (hand-rolled fake `ServerCallContext` — `Grpc.Core.Testing` does not exist on grpc-dotnet;
+copy ScadaBridge's `LocalDbSyncAuthInterceptorTests.cs` fake): non-sync method passes with no key;
+sync + no configured key → PermissionDenied; wrong bearer → PermissionDenied; correct bearer → passes.
+
+Write tests first (fail), implement, `dotnet test --filter "FullyQualifiedName~LocalDbSyncAuthInterceptor"`,
+commit `feat(localdb): fail-closed bearer interceptor for the sync endpoint`.
+
+---
+
+### Task 4: `LocalDbRegistration` + Program.cs DI wiring + config defaults
+
+**Classification:** high-risk (touches Program.cs / role gating)
+**Estimated implement time:** ~5 min
+**Parallelizable with:** none (Task 5 edits the same file)
+
+**Files:**
+- Create: `src/Server/ZB.MOM.WW.OtOpcUa.Host/Configuration/LocalDbRegistration.cs`
+- Modify: `src/Server/ZB.MOM.WW.OtOpcUa.Host/Program.cs` (inside the `hasDriver` branch)
+- Modify: `src/Server/ZB.MOM.WW.OtOpcUa.Host/appsettings.json`
+
+**Step 1:** `LocalDbRegistration`, mirroring `SecretsRegistration`'s shape:
+```csharp
+namespace ZB.MOM.WW.OtOpcUa.Host.Configuration;
+
+internal static class LocalDbRegistration
+{
+    /// Driver-role nodes only. Storage is unconditional; replication stays inert until
+    /// LocalDb:Replication:PeerAddress (initiator) / LocalDb:SyncListenPort (listener) are set.
+    public static IServiceCollection AddOtOpcUaLocalDb(
+        this IServiceCollection services, IConfiguration configuration)
+    {
+        services.AddZbLocalDb(configuration, LocalDbSetup.OnReady);
+        services.AddZbLocalDbReplication(configuration);
+        return services;
+    }
+
+    public static int SyncListenPort(IConfiguration configuration) =>
+        configuration.GetValue<int>("LocalDb:SyncListenPort");
+}
+```
+
+**Step 2:** Program.cs, in the `hasDriver` block (near `AddAlarmHistorian`):
+`builder.Services.AddOtOpcUaLocalDb(builder.Configuration);` and
+`builder.Services.AddGrpc(o => o.Interceptors.Add<LocalDbSyncAuthInterceptor>());`
+(AddGrpc only under `hasDriver` — admin-only nodes expose no sync surface).
+
+**Step 3:** appsettings.json:
+```json
+"LocalDb": {
+  "Path": "./data/otopcua-localdb.db",
+  "SyncListenPort": 0,
+  "Replication": {}
+}
+```
+`LocalDb:Path` is `ValidateOnStart`-required once `AddZbLocalDb` runs — since registration is
+driver-gated, admin-only configs need nothing. Check the role-overlay files
+(`appsettings.driver.json` / `appsettings.admin-driver.json`) and any deploy templates for
+conflicting `LocalDb` keys.
+
+**Step 4:** Build + full Host unit tests. Verify an admin-only graph doesn't require the key: this
+is pinned properly in Task 10's integration tests, but do a quick
+`OTOPCUA_ROLES=admin dotnet run` smoke only if cheap; otherwise rely on Task 10.
+
+**Step 5: Commit.** `feat(localdb): wire AddOtOpcUaLocalDb into the driver role`
+
+---
+
+### Task 5: Dedicated h2c sync listener + endpoint mapping (THE Kestrel task)
+
+**Classification:** high-risk
+**Estimated implement time:** ~5 min
+**Parallelizable with:** none (Program.cs)
+
+**Files:**
+- Modify: `src/Server/ZB.MOM.WW.OtOpcUa.Host/Program.cs`
+
+**Why high-risk:** the Host today binds exclusively via `ASPNETCORE_URLS=http://+:9000`. Any
+explicit `ConfigureKestrel(... Listen*)` makes Kestrel **ignore URLs entirely** (it logs
+"Overriding address(es)"), which would silently kill the AdminUI/deploy API behind Traefik.
+
+**Step 1:** Add, before `builder.Build()`:
+```csharp
+var syncPort = LocalDbRegistration.SyncListenPort(builder.Configuration);
+if (hasDriver && syncPort > 0)
+{
+    // Explicit Listen* replaces ASPNETCORE_URLS wholesale, so re-bind the primary HTTP
+    // endpoint here too. Parse it from the configured URLs rather than hard-coding 9000.
+    var urls = builder.Configuration["ASPNETCORE_URLS"] ?? builder.Configuration["urls"] ?? "http://+:9000";
+    var httpPort = new Uri(urls.Split(';')[0].Replace("+", "localhost").Replace("*", "localhost")).Port;
+    builder.WebHost.ConfigureKestrel(k =>
+    {
+        k.ListenAnyIP(httpPort);                                            // HTTP/1.1 (existing surface)
+        k.ListenAnyIP(syncPort, o => o.Protocols = HttpProtocols.Http2);    // h2c, prior-knowledge gRPC
+    });
+}
+```
+When `syncPort == 0` (the default) nothing changes — URLs binding stays untouched. Cleartext
+`Http1AndHttp2` cannot serve prior-knowledge h2c, hence the dedicated `Http2`-only listener.
+
+**Step 2:** After the app pipeline's other `Map*` calls, driver-gated:
+```csharp
+if (hasDriver && syncPort > 0)
+{
+    app.MapZbLocalDbSync();
+}
+```
+(Mapping is harmless when unauthenticated — the interceptor fail-closes — but gating on the port
+keeps admin-only and default-OFF graphs entirely free of the endpoint.)
+
+**Step 3: Verify both surfaces.**
+```bash
+dotnet build ZB.MOM.WW.OtOpcUa.slnx
+```
+Then a local smoke with the port on:
+`ASPNETCORE_URLS=http://+:9000 OTOPCUA_ROLES=driver LocalDb__SyncListenPort=9001 dotnet run --project src/Server/ZB.MOM.WW.OtOpcUa.Host ...`
+— expect startup logs to show BOTH `:9000` and `:9001` bound, and `curl -s localhost:9000/healthz`
+(or the mapped health route) still answering. If the app needs SQL to boot, defer the smoke to the
+Task 12 rig check but say so explicitly in the task notes.
+
+**Step 4: Commit.** `feat(localdb): dedicated h2c listener + MapZbLocalDbSync gated on LocalDb:SyncListenPort`
+
+---
+
+### Task 6: `IDeploymentArtifactCache` + chunked LocalDb implementation + tests
+
+**Classification:** standard
+**Estimated implement time:** ~5 min
+**Parallelizable with:** Task 3, Task 5
+
+**Files:**
+- Create: `src/Server/ZB.MOM.WW.OtOpcUa.Runtime/Deployment/IDeploymentArtifactCache.cs`
+- Create: `src/Server/ZB.MOM.WW.OtOpcUa.Runtime/Deployment/LocalDbDeploymentArtifactCache.cs`
+- Test: `tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests/Deployment/LocalDbDeploymentArtifactCacheTests.cs`
+
+**Step 1: Failing tests** (real temp-file `ILocalDb` with `LocalDbSetup.OnReady` applied):
+- round-trip: store a 300 KiB random artifact → `GetCurrentAsync` returns byte-identical payload
+  (forces ≥ 3 chunks at 128 KiB);
+- retention: store 3 deployments for one cluster → only the newest 2 remain in
+  `deployment_artifacts`; pointer names the newest;
+- integrity: corrupt one chunk row via SQL → `GetCurrentAsync` returns null (miss), never a
+  truncated artifact;
+- missing pointer → null.
+
+**Step 2: Implement:**
+```csharp
+public interface IDeploymentArtifactCache
+{
+    Task StoreAsync(string clusterId, string deploymentId, string revisionHash,
+                    byte[] artifact, CancellationToken ct = default);
+    Task<CachedDeploymentArtifact?> GetCurrentAsync(string clusterId, CancellationToken ct = default);
+}
+
+public sealed record CachedDeploymentArtifact(
+    string DeploymentId, string RevisionHash, byte[] Artifact, DateTimeOffset AppliedAtUtc);
+```
+`LocalDbDeploymentArtifactCache(ILocalDb db)`:
+- `StoreAsync`: one `ILocalDbTransaction` — delete any existing chunks for this `deployment_id`
+  (idempotent re-store), insert chunks (raw 128 * 1024 bytes per chunk, `Convert.ToBase64String`),
+  upsert the pointer (`INSERT ... ON CONFLICT(cluster_id) DO UPDATE`), then prune: delete
+  `deployment_artifacts` rows whose `deployment_id` is not among the newest 2 `cached_at_utc` for
+  this `cluster_id`. SHA-256 over the raw artifact into the pointer. ISO-8601 UTC timestamps.
+- `GetCurrentAsync`: read pointer; read chunks `ORDER BY chunk_index`; verify count ==
+  `chunk_count` and SHA-256 matches; return null on any mismatch (log a warning naming which check
+  failed).
+- Use `db.ExecuteAsync`/`QueryAsync` with anonymous-object parameters (`@Name` markers). Remember
+  a `Dictionary<string,string>` parameter **throws** — use anonymous objects.
+
+**Step 3:** run tests → PASS. **Step 4: Commit.**
+`feat(localdb): chunked deployment-artifact cache over ILocalDb`
+
+---
+
+### Task 7: Cache write path in `DriverHostActor`
+
+**Classification:** high-risk (actor model, `Props` expression-tree trap)
+**Estimated implement time:** ~5 min
+**Parallelizable with:** none
+
+**Files:** (exact edit sites come from the Task 0 recon doc — cite it in the commit)
+- Modify: `src/Server/ZB.MOM.WW.OtOpcUa.Runtime/Drivers/DriverHostActor.cs`
+- Modify: the actor-registration site (`WithOtOpcUaRuntimeActors` / DI extension) to provide
+  `IDeploymentArtifactCache`
+- Modify: `src/Server/ZB.MOM.WW.OtOpcUa.Host/Program.cs` or `LocalDbRegistration` — register
+  `IDeploymentArtifactCache` → `LocalDbDeploymentArtifactCache` singleton (driver branch)
+- Test: the **xunit2** TestKit project used for existing DriverHostActor tests (recon names it)
+
+**Steps:**
+1. **Failing test:** after a successful artifact apply, the cache received `StoreAsync` with the
+   applied deployment's id/hash/bytes (inject a recording fake `IDeploymentArtifactCache`).
+   Also: a cache that throws on `StoreAsync` does NOT fail the apply (apply result unchanged, error
+   logged).
+2. Thread the dependency through the actor's constructor. ⚠ `Props.Create` is an expression tree:
+   after adding the parameter, re-check **every** construction site for positional/named-arg
+   rebinding (the recon lists them) — do not rely on the compiler.
+3. Invoke `StoreAsync` fire-and-forget (`PipeTo`-style or a guarded `Task.Run` per the actor's
+   existing async conventions — match whatever pattern the actor already uses for side-effect IO)
+   at the post-apply point identified in recon. Cluster id from the recon-identified source.
+4. Run the actor test suite for this project. Commit:
+   `feat(localdb): DriverHostActor stores applied artifacts in the pair-local cache`
+
+---
+
+### Task 8: Boot-from-cache read path + running-from-cache signal
+
+**Classification:** high-risk
+**Estimated implement time:** ~5 min
+**Parallelizable with:** none
+
+**Files:**
+- Modify: `src/Server/ZB.MOM.WW.OtOpcUa.Runtime/Drivers/DriverHostActor.cs`
+- Test: same xunit2 TestKit project as Task 7
+
+**Steps:**
+1. **Failing tests:**
+   - central fetch fails at startup AND cache has an artifact → the actor applies the cached
+     artifact (assert via whatever observable the apply already exposes) and logs/flags
+     running-from-cache;
+   - central fetch fails AND cache empty → today's behavior exactly (Stale, no apply);
+   - central fetch **succeeds** → cache is NOT consulted (fresh config wins; assert the fake
+     cache's `GetCurrentAsync` was never called on the happy path).
+2. Implement at the recon-identified boot-failure seam. The signal: a log warning at minimum plus,
+   if the actor already publishes health/status (recon says how), a `RunningFromCache` marker on it.
+   Do NOT touch `DispatchDeployment` handling — a new deployment still requires central.
+3. Run tests; commit `feat(localdb): boot from the pair-local artifact cache when central SQL is unreachable`.
+
+---
+
+### Task 9: Delete the dormant LiteDB LocalCache subsystem
+
+**Classification:** small
+**Estimated implement time:** ~3 min
+**Parallelizable with:** Task 6, Task 10, Task 11
+
+**Files:**
+- Delete: `src/Core/ZB.MOM.WW.OtOpcUa.Configuration/LocalCache/` (entire directory:
+  `ILocalConfigCache`, `LiteDbConfigCache`, `GenerationSealedCache`, `ResilientConfigReader`,
+  `GenerationSnapshot`, `StaleConfigFlag`, exceptions)
+- Delete: `tests/Core/ZB.MOM.WW.OtOpcUa.Configuration.Tests/GenerationSealedCacheTests.cs`,
+  `ResilientConfigReaderTests.cs`
+- Modify: `Directory.Packages.props` + the Configuration csproj — remove the `LiteDB` package if
+  nothing else references it (grep first)
+
+**Steps:** Confirm the Task 0 recon's "nothing references it" finding still holds
+(`grep -rn "ILocalConfigCache\|GenerationSealedCache\|ResilientConfigReader\|LiteDB" src/ tests/`),
+delete, build the full solution, run the Configuration test project. DoD phrasing: **no references
+from code** — leave any explanatory prose/comments that point readers at LocalDb instead. Add one
+line to the recon doc noting LiteDB's removal. Commit:
+`refactor(localdb): delete the dormant LiteDB LocalCache (superseded by ZB.MOM.WW.LocalDb)`
+
+---
+
+### Task 10: Health check + telemetry meter allowlist
+
+**Classification:** small
+**Estimated implement time:** ~4 min
+**Parallelizable with:** Task 9, Task 11
+
+**Files:**
+- Create: `src/Server/ZB.MOM.WW.OtOpcUa.Host/Health/LocalDbReplicationHealthCheck.cs` (or the
+  directory `AddOtOpcUaHealth` uses — recon names it)
+- Modify: the `AddOtOpcUaHealth` registration (driver branch)
+- Modify: the observability meter list IF Task 0 found an allowlist
+
+**Steps:**
+1. Failing unit tests: replication unconfigured (no peer, no listener) → `Healthy` (default-OFF
+   must not degrade a plain node); peer configured + `ISyncStatus.Connected == false` → `Degraded`;
+   connected + backlog `null` → `Degraded` (unknown backlog is not healthy); connected + backlog
+   small → `Healthy`.
+2. Implement against `ISyncStatus` + `IOptions<ReplicationOptions>` (peer-configured = non-empty
+   `PeerAddress` OR `SyncListenPort > 0` — pass the latter in via options/config).
+3. **Meter allowlist:** if `AddOtOpcUaObservability` restricts meters, add
+   `"ZB.MOM.WW.LocalDb.Replication"` (use `LocalDbMetrics.MeterName`) — this is a silent allowlist;
+   the ScadaBridge live gate is the proof it bites. If there is no allowlist, record that in the
+   recon doc and skip.
+4. Commit `feat(localdb): replication health check + meter export`.
+
+---
+
+### Task 11: DI-pin integration tests over the real Program.cs
+
+**Classification:** standard
+**Estimated implement time:** ~5 min
+**Parallelizable with:** Task 9, Task 10
+
+**Files:**
+- Test: `tests/Server/ZB.MOM.WW.OtOpcUa.Host.IntegrationTests/LocalDbWiringTests.cs` (xunit.v3,
+  `WebApplicationFactory<Program>` — the project already builds the real Program.cs; set
+  `OTOPCUA_ROLES` per test case the way neighboring tests do)
+
+**Pins (each its own test):**
+1. Driver graph: `ILocalDb` resolves, is a singleton, `ReplicatedTables` ordinal-sorted ==
+   `["deployment_artifacts", "deployment_pointer"]` — exact set, both directions load-bearing.
+2. Driver graph: `IDeploymentArtifactCache` resolves to `LocalDbDeploymentArtifactCache`.
+3. Default-OFF pin: `ISyncStatus` resolves with `Connected == false`, `PeerNodeId == null`.
+4. Admin-only graph: `ILocalDb` is NOT registered (`GetService<ILocalDb>()` is null) and boot does
+   not demand `LocalDb:Path`.
+5. Health: the LocalDb health check is registered in the driver graph.
+
+Point `LocalDb:Path` at a per-test temp file via the factory's config overrides;
+`ClearAllPools` + delete in cleanup. These tests exist because DI extensions without a
+container-built test have shipped inert three times in this family (Secrets 0.2.0/0.2.2,
+ScadaBridge#22). Commit `test(localdb): DI pins over the real host graph`.
+
+---
+
+### Task 12: Two-node convergence harness + tests
+
+**Classification:** high-risk
+**Estimated implement time:** ~5 min (harness) + ~4 min (scenarios) — split the commit if needed
+**Parallelizable with:** none (depends on Tasks 2, 3, 5, 6)
+
+**Files:**
+- Create: `tests/Server/ZB.MOM.WW.OtOpcUa.Host.IntegrationTests/LocalDb/LocalDbPairHarness.cs`
+- Test: `tests/Server/ZB.MOM.WW.OtOpcUa.Host.IntegrationTests/LocalDb/LocalDbPairConvergenceTests.cs`
+
+**Harness:** copy the pattern from
+`~/Desktop/ScadaBridge/tests/ZB.MOM.WW.ScadaBridge.IntegrationTests/LocalDbSitePairHarness.cs` and
+the library's `ConvergenceFixture` (`~/Desktop/scadaproj/ZB.MOM.WW.LocalDb/tests/.../Convergence/ConvergenceFixture.cs`):
+- Two full stacks over a real loopback Kestrel h2c socket (port 0), **through the real
+  `LocalDbSyncAuthInterceptor`** with a shared test key; node A initiator, node B passive.
+- Both initialized via the **production `LocalDbSetup.OnReady`** — a hand-written schema proves
+  only that the test agrees with itself.
+- DBs owned by the harness, registered as pre-constructed singletons (so MS.DI won't dispose them
+  on host teardown); `KillTransportAsync`/`RestartTransportAsync`; tight `FlushInterval` (50 ms),
+  bounded backoff (2 s); temp files, `ClearAllPools` cleanup; a collection definition to serialize
+  these tests.
+
+**Scenarios:**
+1. `ArtifactStoredOnA_ConvergesToB_ByteIdentical` — store a multi-chunk artifact via
+   `LocalDbDeploymentArtifactCache` on A; B's cache returns byte-identical bytes; both nodes'
+   `__localdb_row_version` rows for the pointer carry the **same HLC and origin node id** (B holds
+   A's row, not a re-derived one).
+2. `RetentionPruneOnA_TombstonesReachB` — third deployment on A prunes the first; B's chunk rows
+   for the pruned deployment disappear and `__localdb_row_version WHERE is_tombstone=1` rows exist
+   on B.
+3. `WritesWhileTransportDown_SurviveRejoin` — kill transport, store on A, restart, converge.
+4. `WrongApiKey_NeverConverges` — harness with mismatched keys: assert **no** convergence after a
+   bounded wait AND (positive control) that the same scenario with matching keys converges — an
+   absence assertion without a positive control passed vacuously in ScadaBridge.
+
+**DoD within this task:** temporarily comment out the two `RegisterReplicated` calls and confirm
+scenarios 1–3 go red (run locally, do not commit the red state); restore. Record the red/green
+evidence in the task notes. Commit `test(localdb): 2-node convergence harness + scenarios`.
+
+---
+
+### Task 13: docker-dev rig configuration
+
+**Classification:** small
+**Estimated implement time:** ~4 min
+**Parallelizable with:** Task 14
+
+**Files:**
+- Modify: `docker-dev/docker-compose.yml`
+
+**Steps** (adjust to the recon's findings on volumes/env style):
+1. Every driver node: a named volume (or existing data mount) backing `/app/data`, and
+   `LocalDb__Path=/app/data/otopcua-localdb.db`.
+2. **site-a pair only** (mirror the ScadaBridge default-OFF posture — site-b stays unreplicated as
+   the pin):
+   - site-a-1: `LocalDb__SyncListenPort=9001`, `LocalDb__Replication__PeerAddress=http://site-a-2:9001`,
+     `LocalDb__Replication__ApiKey=dev-site-a-localdb-sync-key`, `LocalDb__Replication__MaxBatchSize=16`
+   - site-a-2: `LocalDb__SyncListenPort=9001`, same `ApiKey`, same `MaxBatchSize`, **no PeerAddress**
+     (passive; the stream is bidirectional).
+   The key must be byte-identical on both — the interceptor fail-closes on any mismatch and the
+   pair silently stops converging.
+3. `MaxBatchSize=16` because batching is row-count-only against gRPC's 4 MB cap and artifact chunk
+   rows are ≈ 171 KB (16 × 171 KB ≈ 2.7 MB worst case).
+4. `docker compose config` to validate; do NOT bring the rig up in this task (the live gate task
+   owns rig runs).
+5. Commit `chore(localdb): rig config — consolidated path everywhere, replication on the site-a pair`.
+
+---
+
+### Task 14: Documentation
+
+**Classification:** small
+**Estimated implement time:** ~4 min
+**Parallelizable with:** Task 13
+
+**Files:**
+- Create: `docs/operations/2026-07-20-localdb-pair-replication.md` (runbook: enable/disable,
+  ApiKey handling via `${secret:}`, stop/start-together rule, tombstone-retention resurrection
+  window, MaxBatchSize row-count-vs-4MB, never host-`sqlite3` a live WAL DB / cp-triplet recipe)
+- Modify: `docs/Redundancy.md` (a short "pair-local config cache" section: what replicates, what
+  boot-from-cache does and does not cover)
+- Modify: `CLAUDE.md` (this repo): LocalDb adoption row/paragraph — state Phase 1 scope, default-OFF,
+  rig-only enablement
+- Modify: `docs/Configuration.md` if it documents config keys (add the `LocalDb` section)
+
+Commit `docs(localdb): phase-1 runbook + redundancy/config docs`.
+
+---
+
+### Task 15: DoD sweep (offline)
+
+**Classification:** standard
+**Estimated implement time:** ~5 min
+**Parallelizable with:** none (final offline task)
+
+**Steps:**
+1. `dotnet build ZB.MOM.WW.OtOpcUa.slnx` → **0 warnings** (warnings-as-errors).
+2. `dotnet test ZB.MOM.WW.OtOpcUa.slnx` → full suite green; record counts. Baseline any
+   pre-existing failures BEFORE this branch (`git stash` → run → unstash) rather than assuming;
+   report deltas only.
+3. Greps (phrase as "no references from code"; explanatory comments may remain):
+   `grep -rn "LiteDB\|ILocalConfigCache\|GenerationSealedCache" src/ tests/` → no code references.
+4. Confirm the positive-control evidence from Task 12 is recorded.
+5. Update `docs/plans/2026-07-20-localdb-adoption-phase1.md.tasks.json` statuses.
+6. Commit `chore(localdb): phase-1 DoD sweep` and STOP. Report: branch name, commit list, test
+   counts, and that the live gate (Task 16) needs the rig + operator go-ahead.
+
+---
+
+### Task 16: Live gate on the docker-dev rig (run only with explicit user go-ahead)
+
+**Classification:** high-risk (rig)
+**Estimated implement time:** ~30 min wall-clock (mostly waiting)
+**Parallelizable with:** none
+
+**Preamble:** All DB inspection via `cp` of the `db`/`-wal`/`-shm` triplet out of the container
+(`docker cp`) and querying the copy — never host `sqlite3` on the live file (it poisons the WAL
+across virtiofs; root cause of the 2026-07-20 ScadaBridge incident). Metrics via
+`docker run --rm --network container:<node> curlimages/curl:latest -s localhost:<port>/metrics`.
+If an anomaly appears within seconds of one of your own measurements, suspect the measurement
+first — restart both nodes and re-run untouched before blaming the library.
+
+**Checks (all must PASS; record evidence in `docs/plans/2026-07-20-localdb-phase1-live-gate.md`):**
+1. Rig up, site-a pair healthy, `/metrics` on both shows `localdb_` series (proves the meter
+   allowlist work).
+2. Deploy a config through the normal deploy API → both site-a nodes' `deployment_pointer` +
+   `deployment_artifacts` rows are byte-identical with **identical HLC + origin node id** (one
+   node's row replicated, not two independent derivations — both nodes also locally store after
+   apply, so expect LWW-converged identical content either way; assert convergence, and note which
+   origin won).
+3. **Boot-from-cache:** stop the SQL container; restart site-a-2; it comes up serving the cached
+   config with the running-from-cache signal in its log; start SQL again; node recovers fresh
+   behavior.
+4. **Replicated-cache payoff:** wipe site-a-2's local DB file (container stopped), restart it with
+   SQL **up**, let replication repopulate the cache from site-a-1, then repeat check 3's SQL-down
+   restart — it boots from a cache it never wrote itself.
+5. Transport kill (pause site-a-2 container): store/deploy on a-1, oplog depth rises; unpause;
+   drains to 0; converged.
+6. Retention: deploy a 3rd config; pruned deployment's chunks gone on BOTH nodes with tombstone
+   rows present on both.
+7. Both-nodes-together restart: clean rejoin, identical counts, zero
+   `disk I/O error`/`SQLITE_IOERR`/`corrupt` in either log.
+8. site-b pair (default-OFF pin): LocalDb file exists and works locally, `ISyncStatus` health
+   Healthy, no sync connections, no listener on 9001.
+
+Record PASS/FAIL per check with the actual evidence (row counts, md5s, log lines). Commit the gate
+doc. Do not merge — report.
+
+---
+
+## Task persistence
+
+Tasks file: `docs/plans/2026-07-20-localdb-adoption-phase1.md.tasks.json` (same directory).
+Update statuses as tasks complete; any deviation from this plan gets a `deviation` note on the task
+(the ScadaBridge tasks.json convention — the record of *why* is what makes the plan auditable).
@@ -0,0 +1,153 @@
+{
+  "planPath": "docs/plans/2026-07-20-localdb-adoption-phase1.md",
+  "tasks": [
+    {
+      "id": 0,
+      "subject": "Task 0: Preflight + recon (findings doc, STOP conditions)",
+      "status": "completed",
+      "notes": "Feed verified: LocalDb/.Contracts/.Replication all 0.1.1. All 3 STOP conditions clear. Findings: docs/plans/2026-07-20-localdb-phase1-recon.md. 8 deviations recorded (D-1..D-8); D-1/D-3/D-5/D-6 change downstream work materially.",
+      "deviation": "D-1 cache read cannot be keyed by ClusterId at the boot seam (unkeyed newest-pointer read instead); D-3 a third LiteDB test file must be deleted; D-5 WebApplicationFactory<Program> is deliberately unused in this repo (use TwoNodeClusterHarness); D-6 driver-only nodes have no ASPNETCORE_URLS so the Kestrel re-bind fallback is wrong. See recon doc \u00a79."
+    },
+    {
+      "id": 1,
+      "subject": "Task 1: Package references and pins (LocalDb 0.1.1, Grpc.AspNetCore, SQLitePCLRaw)",
+      "status": "completed",
+      "blockedBy": [
+        0
+      ]
+    },
+    {
+      "id": 2,
+      "subject": "Task 2: Schema + LocalDbSetup.OnReady + registration tests",
+      "status": "completed",
+      "blockedBy": [
+        1
+      ]
+    },
+    {
+      "id": 3,
+      "subject": "Task 3: Fail-closed sync auth interceptor + tests",
+      "status": "completed",
+      "blockedBy": [
+        1
+      ]
+    },
+    {
+      "id": 4,
+      "subject": "Task 4: LocalDbRegistration + Program.cs DI wiring + config defaults",
+      "status": "completed",
+      "blockedBy": [
+        2,
+        3
+      ]
+    },
+    {
+      "id": 5,
+      "subject": "Task 5: Dedicated h2c sync listener + MapZbLocalDbSync (Kestrel URLs-override risk)",
+      "status": "completed",
+      "blockedBy": [
+        4
+      ]
+    },
+    {
+      "id": 6,
+      "subject": "Task 6: IDeploymentArtifactCache + chunked LocalDb implementation + tests",
+      "status": "completed",
+      "blockedBy": [
+        2
+      ]
+    },
+    {
+      "id": 7,
+      "subject": "Task 7: Cache write path in DriverHostActor (Props expression-tree trap)",
+      "status": "completed",
+      "blockedBy": [
+        0,
+        6
+      ]
+    },
+    {
+      "id": 8,
+      "subject": "Task 8: Boot-from-cache read path + running-from-cache signal",
+      "status": "completed",
+      "blockedBy": [
+        7
+      ]
+    },
+    {
+      "id": 9,
+      "subject": "Task 9: Delete the dormant LiteDB LocalCache subsystem",
+      "status": "completed",
+      "blockedBy": [
+        0
+      ]
+    },
+    {
+      "id": 10,
+      "subject": "Task 10: Health check + telemetry meter allowlist",
+      "status": "completed",
+      "blockedBy": [
+        4
+      ]
+    },
+    {
+      "id": 11,
+      "subject": "Task 11: DI-pin integration tests over the real Program.cs",
+      "status": "completed",
+      "blockedBy": [
+        5,
+        10
+      ]
+    },
+    {
+      "id": 12,
+      "subject": "Task 12: Two-node convergence harness + scenarios (+ positive control)",
+      "status": "completed",
+      "blockedBy": [
+        5,
+        6
+      ]
+    },
+    {
+      "id": 13,
+      "subject": "Task 13: docker-dev rig configuration (site-a pair on, site-b pin off)",
+      "status": "completed",
+      "blockedBy": [
+        5
+      ]
+    },
+    {
+      "id": 14,
+      "subject": "Task 14: Documentation (runbook, Redundancy.md, CLAUDE.md)",
+      "status": "completed",
+      "blockedBy": [
+        8
+      ]
+    },
+    {
+      "id": 15,
+      "subject": "Task 15: DoD sweep (offline) \u2014 STOP and report after this",
+      "status": "completed",
+      "blockedBy": [
+        7,
+        8,
+        9,
+        11,
+        12,
+        13,
+        14
+      ],
+      "notes": "Offline DoD sweep: full-solution build 0 errors (824 pre-existing OTOPCUA0001 analyzer warnings in driver *test* projects; none reference any LocalDb/DeploymentCache file). Grep: no LiteDB/ILocalConfigCache/GenerationSealedCache code refs (2 explanatory doc-comment lines in ILdapGroupRoleMappingService remain, allowed). Runtime.Tests 407/0/31 twice (the previously-flagged intermittent did NOT reproduce). Host.IntegrationTests LocalDb subset 40/0/0. Full-solution `dotnet test` with stash-baseline NOT run: many suites are infra-gated (driver fixtures, full Akka mesh, LDAP real-bind, shared-SQL DB tests) and cannot run offline on macOS \u2014 deferred to Task 16 / CI. Task 12 positive-control evidence recorded in commit afa5be71. Did NOT merge to master \u2014 stopped here per plan."
+    },
+    {
+      "id": 16,
+      "subject": "Task 16: Live gate on the docker-dev rig (needs explicit user go-ahead)",
+      "status": "completed",
+      "blockedBy": [
+        15
+      ],
+      "notes": "Live gate RAN on the docker-dev rig with explicit user go-ahead. 8/8 checks pass (check 4 with a documented limitation). Caught + fixed FOUR real defects offline tests missed (4b2f0e6e NU1101 packageSourceMapping, ce9fa07f ASPNETCORE_HTTP_PORTS re-bind, 9137cb41 empty-address-space-on-cache-boot, c6a9f93a cache-not-repopulated-on-RestoreApplied), each with a regression test. Two documented limitations (follow-ups): no replication back-fill of a fully-wiped node; oplog growth on default-OFF nodes. Post-fix: full build 0 errors, Runtime.Tests 409/0, all LocalDb Host.IntegrationTests green; only consistent failure is the infra-gated AbCip_Green_AgainstSim (sim not up). Evidence: 2026-07-20-localdb-phase1-live-gate.md. NOT merged."
+    }
+  ],
+  "lastUpdated": "2026-07-20T00:00:00Z"
+}
@@ -0,0 +1,293 @@
+# OtOpcUa LocalDb Adoption — Phase 2 Implementation Plan (alarm-historian store-and-forward)
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers-extended-cc:executing-plans to implement this plan task-by-task.
+>
+> **Execution model:** Optimized for **Claude Opus** agents (`claude --model opus`); dispatch
+> `high-risk` tasks on Opus. Branch **`feat/localdb-phase2`** in `~/Desktop/OtOpcUa` (remote
+> `lmxopcua`). **Prerequisite: Phase 1 (`docs/plans/2026-07-20-localdb-adoption-phase1.md`) is
+> merged (or this branch is stacked on it) and its live gate passed.** Do not merge as part of this
+> plan; stop at the DoD task.
+>
+> **Design authority:** `~/Desktop/scadaproj/docs/plans/2026-07-20-otopcua-localdb-design.md` §3.4,
+> D8, D9. Reference implementation for "replace a bespoke store" phasing: ScadaBridge Phase 2
+> (`~/Desktop/ScadaBridge/docs/plans/2026-07-19-localdb-adoption-phase2.md` + its live gate doc).
+
+**Goal:** Move the alarm-historian store-and-forward buffer (today the standalone
+`alarm-historian.db` owned by `SqliteStoreAndForwardSink`) into the consolidated LocalDb file as a
+replicated table with a primary-gated drain, so a redundant pair no longer loses buffered alarm
+history when a node dies — and delete the sink's bespoke file/connection management outright.
+
+**Architecture:** `alarm_sf_events` (TEXT GUID PK) registered in `LocalDbSetup.OnReady`; the sink
+rewired onto `ILocalDb` behind its unchanged public seam; drain gated on the delivered-snapshot
+Primary role via `PrimaryGatePolicy` (at-least-once across failover, accepted and documented); a
+one-time idempotent migrator from the legacy file, running **after** registration.
+
+**Risk framing (from ScadaBridge):** Phase 2 replaces a *working* mechanism — a harder risk class
+than Phase 1's "add where none existed." Cutover (delete + rewire) lands in **one commit**; there is
+no dual-mechanism period, and the cutover is the test.
+
+**Hard rules:** identical to Phase 1's list (OnReady ordering, no autoincrement/BLOB, fail-closed
+auth already in place, no in-memory SQLite in tests, cp-triplet-only rig inspection), plus:
+- **Legacy-copy column lists must INTERSECT** with what the legacy file actually has
+  (`pragma_table_info` probe) — a missing column throws and readers silently discard every row.
+- Absence assertions need a positive control.
+- DoD greps phrased as "no references from code" (explanatory comments may survive).
+
+---
+
+### Task 0: Recon (produces `docs/plans/2026-07-20-localdb-phase2-recon.md`)
+
+**Classification:** standard
+**Estimated implement time:** ~5 min
+**Parallelizable with:** none
+
+**Files:**
+- Create: `docs/plans/2026-07-20-localdb-phase2-recon.md`
+- Read-only: `src/Core/ZB.MOM.WW.OtOpcUa.Core.AlarmHistorian/SqliteStoreAndForwardSink.cs` (and the
+  whole `Core.AlarmHistorian` project), `src/Server/ZB.MOM.WW.OtOpcUa.Runtime/Historian/AlarmHistorianOptions.cs`,
+  the drain worker (whatever forwards batches to `GatewayHistorian`/`SendEvent`),
+  `src/Server/ZB.MOM.WW.OtOpcUa.Runtime/Drivers/PrimaryGatePolicy.cs`,
+  `src/Server/ZB.MOM.WW.OtOpcUa.Runtime/Drivers/DriverHostActor.cs` (how `_localRole` +
+  driver-member-count reach the gate today)
+
+**Record, with `file:line` citations:**
+1. The sink's exact table schema: name, columns, PK type (**autoincrement?** — decides whether the
+   migrator needs deterministic `mig-{node}-{legacyId}` ids), indices, and any BLOB columns
+   (**STOP condition:** a BLOB payload column cannot be registered — it must become base64 TEXT in
+   the new schema, and the recon must size the largest realistic payload against the 171 KB-ish
+   chunk guidance; alarm events are small JSON, so expect this to be fine, but verify).
+2. The public seam: the interface the drain worker and producers use (e.g. `IAlarmHistorianSink` /
+   enqueue+dequeue+markDelivered+deadLetter methods), so the rewire can keep it byte-compatible.
+3. Semantics to preserve: `Capacity` (1,000,000) enforcement, `MaxAttempts` (10), dead-letter
+   retention (30 d), `BatchSize` (100), `DrainIntervalSeconds` (5) — where each lives.
+4. The drain worker's lifecycle: hosted service or actor? Where a Primary-role check can be
+   injected, and how the delivered-snapshot role (`RedundancyStateChanged` cache) is accessible
+   from it (via `DriverHostActor`, a shared status service, or a message). If the role is only
+   available inside `DriverHostActor`, note the cleanest bridge (e.g. an `IRedundancyRoleView`
+   singleton the actor updates) — that becomes Task 4's shape.
+5. Whether the sink is constructed per-node config path (`AlarmHistorian:DatabasePath`) anywhere
+   else (tests, tooling).
+6. How `AlarmHistorian:Enabled=false` short-circuits (NullAlarmHistorianSink) — the rewire must
+   keep the disabled path allocating no LocalDb tables? No: tables are created unconditionally in
+   `OnReady` (cheap, empty); only the sink/drain stay Null. Note this in the doc.
+
+Commit: `docs(localdb): phase-2 recon findings`.
+
+---
+
+### Task 1: `alarm_sf_events` schema + registration (+ tests)
+
+**Classification:** standard
+**Estimated implement time:** ~4 min
+**Parallelizable with:** none (Task 2 depends on it)
+
+**Files:**
+- Create: `src/Core/ZB.MOM.WW.OtOpcUa.Core.AlarmHistorian/AlarmSfSchema.cs` (depends only on
+  `Microsoft.Data.Sqlite`)
+- Modify: `src/Server/ZB.MOM.WW.OtOpcUa.Host/Configuration/LocalDbSetup.cs`
+- Test: extend `LocalDbSetupTests`
+
+Schema shape (adjust column names to the recon's findings — preserve today's semantics):
+```sql
+CREATE TABLE IF NOT EXISTS alarm_sf_events (
+    id               TEXT    NOT NULL PRIMARY KEY,   -- app-minted GUID (never autoincrement)
+    payload_json     TEXT    NOT NULL,
+    enqueued_at_utc  TEXT    NOT NULL,
+    attempts         INTEGER NOT NULL DEFAULT 0,
+    status           TEXT    NOT NULL DEFAULT 'pending',  -- pending | delivered | dead
+    last_attempt_utc TEXT    NULL,
+    dead_at_utc      TEXT    NULL
+);
+CREATE INDEX IF NOT EXISTS ix_alarm_sf_events_status ON alarm_sf_events(status, enqueued_at_utc);
+```
+`OnReady` order becomes: Phase-1 DDL → `AlarmSfSchema.Apply` → the two Phase-1
+`RegisterReplicated` calls → `RegisterReplicated("alarm_sf_events")` → **migrator (Task 5) last**.
+(All DDL may run before all registrations; the invariant is registration-before-writes.)
+
+TDD: failing test first — exact replicated set becomes
+`["alarm_sf_events", "deployment_artifacts", "deployment_pointer"]` (ordinal-sorted; update the
+Phase-1 exact-set pins in the same commit — they are *supposed* to go red here, that's them
+working). Oplog-capture test for an `alarm_sf_events` insert. Commit
+`feat(localdb): alarm_sf_events replicated table`.
+
+---
+
+### Task 2: Rewire the sink onto `ILocalDb` + delete bespoke file management (the cutover commit, part 1 of 2 — see Task 3)
+
+**Classification:** high-risk
+**Estimated implement time:** ~5 min
+**Parallelizable with:** none
+
+**Files:**
+- Modify: `src/Core/ZB.MOM.WW.OtOpcUa.Core.AlarmHistorian/SqliteStoreAndForwardSink.cs` (or replace
+  with `LocalDbStoreAndForwardSink.cs` — keep the public seam identical either way)
+- Modify: its registration (`AddAlarmHistorian`) to inject `ILocalDb`
+- Modify: `src/Server/ZB.MOM.WW.OtOpcUa.Runtime/Historian/AlarmHistorianOptions.cs` — remove
+  `DatabasePath` (a breaking config key removal: note it in the runbook/CHANGELOG task)
+- Test: the sink's existing unit tests, rewired to a temp-file `ILocalDb` via `TestLocalDb`-style
+  helper (create `tests/.../TestSupport` helper if none exists — real DB, never a stub: a stubbed
+  bare `SqliteConnection` lacks `zb_hlc_next()` and fails closed on registered tables)
+
+**Steps:**
+1. Write/port failing tests for the seam's semantics: enqueue, drain batch of `BatchSize`,
+   `MaxAttempts` → dead-letter, capacity enforcement, dead-letter retention purge.
+2. Implement over `ILocalDb.ExecuteAsync/QueryAsync` (anonymous-object params). Delete the private
+   connection/pragma/file-open code and any `PRAGMA journal_mode` calls (LocalDb owns pragmas).
+   GUIDs minted at enqueue (`Guid.NewGuid().ToString("N")`).
+3. `Capacity` enforcement: count-based insert guard (preserve today's overflow behavior per recon).
+4. Core.AlarmHistorian gains a package ref on core `ZB.MOM.WW.LocalDb` (interface only).
+5. Build + project tests green. **Commit together with Task 3** if the drain gate can't compile
+   separately (the ScadaBridge tasks-14/15/16 circular-dependency landmine — check before assuming
+   they're independent commits).
+
+---
+
+### Task 3: Primary-gated drain
+
+**Classification:** high-risk
+**Estimated implement time:** ~5 min
+**Parallelizable with:** none
+
+**Files:** (exact shape from recon item 4)
+- Modify: the drain worker
+- Create (if recon says so): `src/Server/ZB.MOM.WW.OtOpcUa.Runtime/Redundancy/IRedundancyRoleView.cs`
+  — a singleton snapshot (`RedundancyRole? LocalRole`, `int DriverMemberCount`) updated by
+  `DriverHostActor` where it already caches `_localRole`
+- Test: drain-worker tests + an actor test pinning that `DriverHostActor` publishes role changes to
+  the view
+
+**Semantics:**
+- Drain runs only when `PrimaryGatePolicy.ShouldServiceAsPrimary(localRole, driverMemberCount)` is
+  true — same policy, same boot-window posture (unknown role drains only when the node is alone).
+- Delivered/dead-letter marks are row UPDATEs → they replicate, so the standby's copy tracks drain
+  progress and does not re-deliver already-marked rows after failover.
+- **At-least-once across failover is accepted:** rows delivered on the old primary whose
+  `delivered` mark hadn't replicated yet will be re-sent by the new primary. Document in the
+  runbook (Task 7); do NOT build dedup.
+- When replication is OFF (default), the gate still applies but `driverMemberCount` for a solo
+  node keeps today's behavior — verify with a test: single-node, role unknown → drains (no
+  regression for unpaired deployments).
+
+TDD: failing tests — secondary role does not drain; primary drains; unknown+alone drains;
+unknown+paired does not. Commit (with Task 2 if coupled):
+`feat(localdb): alarm S&F on LocalDb with primary-gated drain (cutover)`.
+
+---
+
+### Task 4: One-time legacy migrator (`alarm-historian.db` → consolidated)
+
+**Classification:** standard
+**Estimated implement time:** ~5 min
+**Parallelizable with:** Task 6
+
+**Files:**
+- Create: `src/Server/ZB.MOM.WW.OtOpcUa.Host/Configuration/AlarmSfLegacyMigrator.cs`
+- Modify: `LocalDbSetup.OnReady` — call it **last**, after all `RegisterReplicated` calls
+- Test: `tests/Server/ZB.MOM.WW.OtOpcUa.Host.Tests/AlarmSfLegacyMigratorTests.cs`
+
+Mirror `~/Desktop/ScadaBridge/src/ZB.MOM.WW.ScadaBridge.Host/SiteLocalDbLegacyMigrator.cs`:
+- Source path from the pre-removal `AlarmHistorian:DatabasePath` default (`alarm-historian.db`) —
+  read the raw config key even though the option property is gone.
+- `ShouldMigrate`: skip if file missing or `<file>.migrated` exists. `:memory:`/`file:` sources → no-op.
+- **If the legacy PK is autoincrement (recon):** deterministic ids `mig-{NodeName}-{legacyId}`
+  (node name from the recon-identified config key) — rerunnable without duplicates under
+  `INSERT OR IGNORE`, and no cross-node collision. If already GUIDs, copy as-is.
+- One transaction for the whole copy; `File.Move(path, path + ".migrated")` only after commit;
+  failure throws out of `OnReady` → boot fails, legacy untouched.
+- **Column intersection** via `pragma_table_info` on the legacy table; required-PK guard.
+- Both pair nodes migrate independently; their rows have distinct ids (node-prefixed), so the
+  merged buffer is the union — expected; note that the new primary will drain the standby's
+  migrated rows too.
+
+TDD: failing tests — happy path row counts; idempotent re-run; failure leaves legacy file
+untouched; migrated rows **enter the oplog** (assert `__localdb_oplog` — the registration-order
+pin); older legacy file missing a column still migrates (intersection). Commit
+`feat(localdb): one-time alarm-historian.db migrator`.
+
+---
+
+### Task 5: Convergence + failover scenarios in the pair harness
+
+**Classification:** high-risk
+**Estimated implement time:** ~5 min
+**Parallelizable with:** Task 4
+
+**Files:**
+- Test: `tests/Server/ZB.MOM.WW.OtOpcUa.Host.IntegrationTests/LocalDb/AlarmSfConvergenceTests.cs`
+  (reuses the Phase-1 `LocalDbPairHarness`)
+
+**Scenarios:**
+1. `AlarmBurstOnA_ConvergesToB_AndOplogDrains` — enqueue N events on A; identical rowset on B;
+   oplog → 0.
+2. `DeliveredMarksReplicate` — mark rows delivered on A; B's copies show delivered (the
+   no-redeliver-after-failover property, asserted at the data layer).
+3. `WritesWhileTransportDown_SurviveRejoin`.
+4. Positive control: with `RegisterReplicated("alarm_sf_events")` commented out, scenarios 1–3 go
+   red (run locally, record, restore — do not commit red).
+
+Commit `test(localdb): alarm S&F convergence scenarios`.
+
+---
+
+### Task 6: Rig config + docs
+
+**Classification:** small
+**Estimated implement time:** ~4 min
+**Parallelizable with:** Task 4
+
+**Files:**
+- Modify: `docker-dev/docker-compose.yml` — enable `AlarmHistorian__Enabled=true` on the site-a
+  pair if not already (the gate needs a live buffer); remove any `AlarmHistorian__DatabasePath`
+  env vars (key deleted).
+- Modify: `docs/operations/2026-07-20-localdb-pair-replication.md` — add: alarm S&F replication
+  semantics, at-least-once-across-failover statement, migrator behavior (`.migrated` sidecar),
+  `DatabasePath` key removal.
+- Modify: `docs/AlarmHistorian.md` + `CLAUDE.md` — sink now lives in the consolidated LocalDb;
+  drain is primary-gated.
+
+Commit `docs+chore(localdb): phase-2 rig config + docs`.
+
+---
+
+### Task 7: DoD sweep (offline)
+
+**Classification:** standard
+**Estimated implement time:** ~5 min
+**Parallelizable with:** none
+
+1. Full solution build → 0 warnings; full test suite green (deltas vs pre-branch baseline only).
+2. Greps, phrased as "no references from **code**": the old bespoke connection management
+   (`AlarmHistorian:DatabasePath`, direct `new SqliteConnection` inside Core.AlarmHistorian except
+   via schema helpers/tests) — explanatory comments may remain.
+3. Positive-control evidence from Task 5 recorded.
+4. Exact-set replicated-tables pin = 3 tables, both directions.
+5. Update `…phase2.md.tasks.json`; commit `chore(localdb): phase-2 DoD sweep`; STOP and report.
+
+---
+
+### Task 8: Live gate on the docker-dev rig (run only with explicit user go-ahead)
+
+**Classification:** high-risk (rig)
+**Estimated implement time:** ~30 min wall-clock
+**Parallelizable with:** none
+
+Same inspection rules as Phase 1's gate (cp-triplet, curl sidecar, observer-suspicion rule).
+Record in `docs/plans/2026-07-20-localdb-phase2-live-gate.md`:
+1. Migration ran: `.migrated` sidecar present on both site-a nodes; row counts match legacy.
+2. Alarm burst (drive a real driver alarm or the historian-gateway-unreachable path) converges:
+   identical rowsets, oplog drains to 0, dead letters 0.
+3. Only the primary drains: stop the historian gateway egress, buffer builds on BOTH nodes'
+   tables (replicated), but only the primary's drain worker logs attempts.
+4. Failover: stop the primary; the standby (new primary) resumes draining the shared buffer;
+   count of double-delivered events observed and recorded (at-least-once evidence, not a failure).
+5. Both-nodes-together restart clean; zero `disk I/O error`/`SQLITE_IOERR` in logs.
+6. site-b (default-OFF pin): sink works locally, no sync traffic.
+
+Commit the gate doc; report; do not merge.
+
+---
+
+## Task persistence
+
+Tasks file: `docs/plans/2026-07-20-localdb-adoption-phase2.md.tasks.json`. Record deviations per
+task — especially if Tasks 2/3 had to land as one commit (the expected outcome).
@@ -0,0 +1,15 @@
+{
+  "planPath": "docs/plans/2026-07-20-localdb-adoption-phase2.md",
+  "tasks": [
+    { "id": 0, "subject": "Task 0: Recon — sink schema, seam, drain lifecycle, role-view bridge (STOP conditions)", "status": "pending" },
+    { "id": 1, "subject": "Task 1: alarm_sf_events schema + registration (+ exact-set pin update)", "status": "pending", "blockedBy": [0] },
+    { "id": 2, "subject": "Task 2: Rewire sink onto ILocalDb + delete bespoke file management (cutover 1/2)", "status": "pending", "blockedBy": [1] },
+    { "id": 3, "subject": "Task 3: Primary-gated drain via PrimaryGatePolicy (cutover 2/2 — may co-commit with Task 2)", "status": "pending", "blockedBy": [2] },
+    { "id": 4, "subject": "Task 4: One-time alarm-historian.db legacy migrator", "status": "pending", "blockedBy": [3] },
+    { "id": 5, "subject": "Task 5: Convergence + failover scenarios in the pair harness (+ positive control)", "status": "pending", "blockedBy": [3] },
+    { "id": 6, "subject": "Task 6: Rig config + docs", "status": "pending", "blockedBy": [3] },
+    { "id": 7, "subject": "Task 7: DoD sweep (offline) — STOP and report after this", "status": "pending", "blockedBy": [4, 5, 6] },
+    { "id": 8, "subject": "Task 8: Live gate on the docker-dev rig (needs explicit user go-ahead)", "status": "pending", "blockedBy": [7] }
+  ],
+  "lastUpdated": "2026-07-20T00:00:00Z"
+}
@@ -0,0 +1,93 @@
+# LocalDb Phase 1 — live gate (docker-dev rig)
+
+> Task 16 of `2026-07-20-localdb-adoption-phase1.md`. Evidence log for the 8 live-rig checks.
+> Rig: local `docker-dev/docker-compose.yml` (6 host nodes, one shared SQL). site-a pair replicates;
+> central + site-b are default-OFF.
+>
+> **Safety rules followed:** all DB inspection via `docker cp` of the `db`/`-wal`/`-shm` triplet out
+> of the container, querying the copy — never host `sqlite3` on the live WAL file. Metrics via a
+> `curlimages/curl` sidecar with `--network container:<node>` (`aspnet:10.0` has no curl).
+
+## Rig build/up
+
+Two real defects surfaced by the rebuild (both fixed on-branch, re-verified):
+
+1. **`NU1101` — packageSourceMapping gap** (`4b2f0e6e`). `ZB.MOM.WW.LocalDb*` was not mapped to the
+   `dohertj2-gitea` feed, so any *clean* restore (Docker image build, CI, fresh clone) failed. Local
+   dev builds masked it via the warm global NuGet cache. Fixed by adding the two patterns; verified
+   with a temp-packages-dir restore.
+2. **`ASPNETCORE_HTTP_PORTS` re-bind gap** (`ce9fa07f`). The Kestrel re-bind read only
+   `urls`/`ASPNETCORE_URLS`; the aspnet:8.0+ base image sets `ASPNETCORE_HTTP_PORTS=8080` (all
+   interfaces) as the container default instead. A driver node that never sets `URLS` fell through to
+   `localhost:5000`, silently moving its health/metrics surface to loopback. Central nodes were fine
+   (they set `ASPNETCORE_URLS=9000` explicitly). Fixed to fall through URLS → HTTP_PORTS/HTTPS_PORTS →
+   5000; 4 new unit tests. After the fix, driver nodes bind `[::]:8080` + `[::]:9001` (site-a) /
+   `[::]:8080` only (site-b).
+
+Rig: 6 nodes rebuilt from branch `feat/localdb-phase1` @ `ce9fa07f`, all up.
+
+## Checks
+
+| # | Check | Result | Evidence |
+|---|---|---|---|
+| 1 | Rig up, site-a pair healthy, `/metrics` shows `localdb_` series | ✅ PASS | Both site-a nodes `/healthz` 200 Healthy; `/metrics` shows `localdb_oplog_depth` + `localdb_sync_reconnects_total` on meter `ZB.MOM.WW.LocalDb.Replication` (allowlist works); site-a-2 served `/localdb_sync.v1.LocalDbSync/Sync` with routing `match_status=success` (interceptor passed, session established); both oplogs depth 0 |
+| 2 | Deploy → both site-a nodes' pointer + artifacts byte-identical, same HLC + origin | ✅ PASS | Deploy `6e687451…` (rev `efb04c79…`) via `POST :9200/api/deployments` → both site-a-1 and site-a-2 `deployment_pointer` = `SITE-A / 6e687451… / efb04c79… / sha EFB04C79…` (identical); artifact 1 chunk each; **pointer `__localdb_row_version` identical on both: hlc `116955620225646592`, origin node_id `a0576df6-…`, tombstone 0** — one row replicated, not two derivations; both oplogs depth 0 |
+| 3 | Boot-from-cache: SQL down, restart site-a-2, serves cached config w/ signal | ✅ PASS (found + fixed a defect) | With SQL stopped, site-a-2 restart logged `RUNNING FROM CACHE — … booted deployment 6e687451…`; **address space materialised from the cached blob**: `AddressSpaceApplier: applied plan (added=18)` / `OpcUaPublish: applied rebuild (added=18)`. Browse confirms **16 nodes on site-a-2 = 16 on site-a-1**. **Defect the gate caught (`9137cb41`):** pre-fix the rebuild re-read the artifact from the down ConfigDb and no-op'd, so the cache-booted node served **1** node vs the healthy peer's 16 — it logged success but browsed empty. Fixed by passing the in-hand cached blob to `RebuildAddressSpace`; regression test added |
+| 4 | Replicated-cache payoff: wipe a-2 DB, repopulate, then SQL-down boot | ⚠️ PARTIAL — 1 defect fixed; the limitation is since **CLOSED** (LocalDb 0.1.2 — see Summary) | Wiped a-2's LocalDb volume, restarted with **SQL down**: sync session re-established (a-2 served a `Sync` call) but a-2's cache stayed **0/0/0** and a-1's oplog was **0** — the deploy's rows had been acked by the old a-2 and pruned, so there was no delta to send and **no snapshot-resync fired**. ⇒ **Limitation: pure replication does not back-fill a fully-wiped, already-converged node** (library delta-replication; snapshot-resync is gated on the oplog cap, which the running engine never hits). Separately found a **defect (`c6a9f93a`)**: recovery via `RestoreApplied` never wrote the cache (only fresh `ApplyAndAck` did), so a wiped node stayed cache-less. Fixed: `RestoreApplied` now re-caches. Verified — after the fix, wiped a-2 restarted with SQL up: `restored served state … on bootstrap` → cache repopulated `SITE-A / 6e687451`, chunks=1. **Net: a wiped node self-heals its cache from central on next boot (regaining boot-from-cache for future outages); it is not back-filled by its peer during the same outage.** |
+| 5 | Transport kill: pause a-2, oplog rises; unpause, drains to 0 | ✅ PASS | `docker pause` on a-2 severed the sync transport; during the window a-2 accumulated **oplog=2** unacked local writes (its re-cache) while a-1 held 0. `docker unpause` → a-2's oplog **drained to 0 within 5s**, both converged on the same pointer. Note: the rig's redeploys carry an identical revision, so a fresh cache write on a-1 short-circuits (no-op) — the store-during-partition variant is covered by the automated harness scenario `WritesWhileTransportDown_SurviveRejoin` (proven red without `RegisterReplicated`) |
+| 6 | Retention: 3rd deploy prunes oldest; chunks gone + tombstones on BOTH nodes | ✅ PASS | Cached 3 distinct deployment-ids (via deploy + restart re-cache). Both nodes retain exactly the newest 2 (`475df87a`, `962962dc`); the oldest `6e687451`'s chunks are **0 on both** (pruned); **1 artifact tombstone on both** — the prune replicated as a tombstone, not left as a live chunk |
+| 7 | Both-nodes-together restart: clean rejoin, identical counts, no I/O errors | ✅ PASS | Restarted site-a-1 + site-a-2 together: **0** `disk I/O error`/`SQLITE_IOERR`/`corrupt` lines in either log; both re-cached and converged to **identical** counts (ptr `962962dc…`, chunks=2, rowver=3). Byte-identical convergence preserved across a simultaneous restart |
+| 8 | site-b default-OFF pin: cache works locally, Healthy, no sync listener on 9001 | ✅ PASS (+1 finding, since **CLOSED** by the skip-if-unchanged cache write — see Summary) | site-b-1 cache works locally (`SITE-B / 6e687451`, chunks=1, from its own apply); listeners **`[::]:8080` only — no 9001**; port 9001 **not bound** (`/proc/net/tcp`); `/healthz` **200**; no sync/reconnect metric series. **Finding (follow-up, not a blocker):** `localdb_oplog_depth=5` — because `OnReady` registers replication unconditionally, a default-OFF node captures cache writes into its oplog but has no peer to ack/prune them, so the oplog grows slowly (≈2 rows/deploy, amplified by the re-cache-on-restore fix). Bounded by the library `MaxOplogRows` cap (1M); worth a periodic pruner or skip-if-unchanged in a follow-up |
+
+## Summary
+
+**8/8 checks pass** (check 4 with a documented limitation). The gate exercised the real image built
+from the branch, the real interceptor over a real loopback+cross-container h2c transport, and real
+`docker cp`-triplet DB inspection — and caught **four real defects that every offline test had
+missed**, each now fixed on-branch with a regression test:
+
+1. **`NU1101` packageSourceMapping gap** (`4b2f0e6e`) — `ZB.MOM.WW.LocalDb*` unmapped to the gitea
+   feed; every clean restore (Docker, CI, fresh clone) failed. Masked locally by the warm NuGet cache.
+2. **`ASPNETCORE_HTTP_PORTS` re-bind gap** (`ce9fa07f`) — the sync-listener re-bind ignored the
+   aspnet:8.0+ container-default port var, silently moving driver health/metrics to loopback:5000.
+3. **Empty address space on boot-from-cache** (`9137cb41`) — the rebuild re-read the artifact from the
+   down ConfigDb and no-op'd, so a cache-booted node logged success but served clients **1 node vs the
+   healthy peer's 16**. The single most important find: boot-from-cache was half-working.
+4. **Cache not repopulated on `RestoreApplied`** (`c6a9f93a`) — a wiped/fresh-volume node recovered its
+   served state from central but stayed cache-less, unable to boot-from-cache on the next outage.
+
+**Two documented limitations (follow-ups, not blockers) — both since CLOSED:**
+
+- **No replication back-fill of a fully-wiped node** (check 4): a peer's already-acked cache rows are
+  pruned from its oplog and snapshot-resync is gated on the (never-hit) oplog cap, so a wiped node is
+  not healed by its peer — it self-heals from central on next boot instead.
+  → **FIXED in `ZB.MOM.WW.LocalDb` 0.1.2 + 0.1.3** (scadaproj `cad3bcb` + `3b7489a`), live-gated in
+  `2026-07-21-localdb-followups-live-gate.md`. The diagnosis in this doc was
+  slightly off: the cap was not the gate. `ComputeSnapshotRequiredAsync` measured the peer's gap
+  against the *oldest surviving oplog row* and read an empty oplog as "no gap possible" — and an
+  empty oplog is the **steady state of a converged pair**, since ack-pruning deletes everything the
+  peer has confirmed. So the healthy state was the one state that could not heal a wiped peer. With
+  an empty oplog the gap is now measured against `last_acked_seq`. Covered at both levels:
+  `SnapshotResyncTests.WipedPeer_AfterEverythingWasAckedAndPruned_StillGetsSnapshot` in the library,
+  and `LocalDbPairConvergenceTests.WipedNode_IsBackFilledByItsPeer_WithoutAnyNewDeploy` here —
+  the latter verified RED against the pinned 0.1.1 and green on 0.1.2. **0.1.3 closes a second,
+  deeper half that only became reachable once back-fill worked:** the rebuilt node's OWN writes were
+  silently dropped, because `last_applied_remote_seq` is a watermark in the *peer's* seq space and a
+  rebuilt peer numbers from 1 again. The follow-up live gate caught that one — offline tests could
+  not have, since the scenario had no test while it was still a documented limitation.
+- **Oplog growth on default-OFF nodes** (check 8): `OnReady` registers replication unconditionally, so
+  a node with no peer accumulates unacked/unpruned oplog rows (~2/deploy). Slow, bounded by the 1M cap;
+  a periodic pruner or a skip-if-unchanged cache write would close it.
+  → **FIXED at the source**: `LocalDbDeploymentArtifactCache.StoreAsync` now **skips entirely** when
+  the pointer already names this deployment/revision, the SHA matches the bytes, and the expected
+  chunk count is present — so re-caching an artifact the node already holds (every restart's
+  boot-from-cache, every `RestoreApplied`) writes nothing and mints no oplog rows. Two guard tests
+  pin what the skip must NOT do (stale bytes under an unchanged revision; a matching pointer over
+  missing chunks), both verified RED against a naive pointer-only skip.
+  Also correcting this row's bound: the growth was never headed for the 1M cap. `AddZbLocalDbReplication`
+  is registered unconditionally, so `MaintenanceBackgroundService` runs on default-OFF nodes too and
+  the **7-day `MaxOplogAge`** cap prunes — the true bound was ~7 days of writes, not 1M rows.
+
+Merged to `master` as `c957db52` (2026-07-21) and pushed. Both follow-ups closed on
+`fix/localdb-phase1-followups` (2026-07-21) and live-gated — see
+`2026-07-21-localdb-followups-live-gate.md`, which found a third defect in the process.
@@ -0,0 +1,72 @@
+# LocalDb Phase 1 — Execution Progress (resume state)
+
+**Branch:** `feat/localdb-phase1` (off `master`). Working tree CLEAN, all work committed, nothing pushed.
+**Plan:** `docs/plans/2026-07-20-localdb-adoption-phase1.md`
+**Recon:** `docs/plans/2026-07-20-localdb-phase1-recon.md` (READ THIS — it has the 8 deviations D-1..D-8 that override the plan text).
+**Skill in use:** `superpowers-extended-cc:executing-plans` — batch, verify, commit per task, report between batches.
+**Do NOT merge to master** — plan stops at Task 15 (DoD) and reports; Task 16 is a rig live-gate needing explicit user go-ahead.
+
+## Status: Tasks 0–9 DONE (10 commits). Tasks 10–16 REMAIN.
+
+| # | Task | State | Commit |
+|---|---|---|---|
+| 0 | Preflight + recon | ✅ | `42f85507` |
+| 1 | Package refs (LocalDb 0.1.1, Grpc.AspNetCore 2.76.0) | ✅ | `44255fcb` |
+| 2 | Schema + LocalDbSetup.OnReady + tests | ✅ | `3b65c24b` |
+| 3 | Fail-closed sync auth interceptor + tests | ✅ | `3d29be83` |
+| 4 | LocalDbRegistration + Program.cs DI + appsettings | ✅ | `6aff9a83` |
+| 5 | h2c sync listener + MapZbLocalDbSync (Kestrel) | ✅ | `b9ddf20e` |
+| (fix) | rename Runtime.Deployment → Runtime.DeploymentCache | ✅ | `e771a11a` |
+| 6 | IDeploymentArtifactCache + chunked impl + tests | ✅ | `a38a52b8` |
+| 9 | Delete LiteDB LocalCache | ✅ | `2bae1b4c` |
+| 7 | Cache write path in DriverHostActor | ✅ | `1becf591` |
+| 8 | Boot-from-cache + RunningFromCache signal | ✅ | `a27eff32` |
+| 10 | Health check + telemetry meter allowlist | ⬜ TODO | |
+| 11 | DI-pin integration tests over real host graph | ⬜ TODO | |
+| 12 | 2-node convergence harness + scenarios | ⬜ TODO | |
+| 13 | docker-dev rig config | ⬜ TODO | |
+| 14 | Documentation | ⬜ TODO | |
+| 15 | DoD sweep (offline) — STOP + report | ⬜ TODO | |
+| 16 | Live gate on docker-dev rig — NEEDS USER GO-AHEAD | ⬜ TODO | |
+
+Native task list (TaskCreate ids 1–17 map to plan tasks 0–16) tracks the same; tasks.json in plan dir mirrors it.
+
+## What exists now (key files)
+
+- `src/Server/ZB.MOM.WW.OtOpcUa.Runtime/Deployment/DeploymentCacheSchema.cs` — DDL, namespace `Runtime.DeploymentCache`.
+- `src/Server/ZB.MOM.WW.OtOpcUa.Runtime/Deployment/IDeploymentArtifactCache.cs` — `StoreAsync` / `GetCurrentAsync` / **`GetCurrentUnkeyedAsync`** (D-1 addition) + `CachedDeploymentArtifact` record.
+- `src/Server/ZB.MOM.WW.OtOpcUa.Runtime/Deployment/LocalDbDeploymentArtifactCache.cs` — chunked impl. NOTE the prune guard `AND deployment_id <> @DeploymentId` (bug I found: pointer-target could be pruned under same-tick GUIDs → permanent silent miss).
+- `src/Server/ZB.MOM.WW.OtOpcUa.Host/Configuration/LocalDbSetup.cs` — `OnReady` (DDL→RegisterReplicated). PUBLIC (Host has no InternalsVisibleTo).
+- `src/Server/ZB.MOM.WW.OtOpcUa.Host/Configuration/LocalDbRegistration.cs` — `AddOtOpcUaLocalDb`, `SyncListenPort(config)`. Registers `IDeploymentArtifactCache → LocalDbDeploymentArtifactCache` singleton.
+- `src/Server/ZB.MOM.WW.OtOpcUa.Host/Configuration/LocalDbSyncAuthInterceptor.cs` — fail-closed bearer.
+- `src/Server/ZB.MOM.WW.OtOpcUa.Host/Configuration/KestrelHttpBinding.cs` — URL parse/re-bind helper (D-6).
+- `src/Server/ZB.MOM.WW.OtOpcUa.Host/Program.cs` — LocalDb wired in `hasDriver` branch (~L176 after AddAlarmHistorian: `AddOtOpcUaLocalDb` + `AddGrpc(interceptor)`); Kestrel re-bind block before `builder.Build()`; `MapZbLocalDbSync()` gated `hasDriver && syncListenPort>0` before `MapOtOpcUaHealth()`.
+- `src/Server/ZB.MOM.WW.OtOpcUa.Host/appsettings.json` — `LocalDb` section (Path, SyncListenPort:0, Replication{}), between AlarmHistorian and Deployment.
+- `src/Server/ZB.MOM.WW.OtOpcUa.Runtime/Drivers/DriverHostActor.cs` — cache dep threaded LAST in Props/ctor/forwarding; `CacheAppliedArtifact` (write, after PushDesiredSubscriptions, empty-blob skip, own try/catch); `TryBootFromCache` + `ApplyCachedArtifact` (in Bootstrap catch); `PushDesiredSubscriptionsFromArtifact` split out; `_isRunningFromCache` field; `SingleClusterCacheKey="__single"`; `ReconcileDrivers` now returns `byte[]?`.
+- `src/Server/ZB.MOM.WW.OtOpcUa.Runtime/ServiceCollectionExtensions.cs` — resolves `IDeploymentArtifactCache` (optional, nullable) and passes into DriverHostActor.Props.
+- `src/Core/ZB.MOM.WW.OtOpcUa.Commons/Interfaces/NodeDiagnosticsSnapshot.cs` — added `bool RunningFromCache = false`.
+- Tests (all green): `Host.IntegrationTests/LocalDbSetupTests.cs`, `LocalDbSyncAuthInterceptorTests.cs`, `LocalDbSyncListenerTests.cs`; `Runtime.Tests/Deployment/LocalDbDeploymentArtifactCacheTests.cs`, `Runtime.Tests/Drivers/DriverHostActorArtifactCacheTests.cs`, `DriverHostActorBootFromCacheTests.cs`.
+
+## Load-bearing facts for the remaining tasks
+
+- **Namespace trap (recurs!):** any `Deployment` child namespace under `Runtime` OR `Runtime.Tests` shadows the `Deployment` EF entity → CS0118 across the assembly. Use `...DeploymentCache`. Only a FULL-SOLUTION build catches it (per-project builds pass).
+- **xUnit1051 is an error** in these test projects: every `ILocalDb`/DB call in a test must pass `TestContext.Current.CancellationToken` (xunit.v3 Host.IntegrationTests) — but `Runtime.Tests` is **xunit v2** (no `TestContext.Current`).
+- **Test project reality (D-5):** NO `Host.Tests` project; NO `WebApplicationFactory<Program>` (deliberately — `TwoNodeClusterHarness.cs:48` explains why). Host unit tests live in `Host.IntegrationTests` (xunit.v3). Actor tests in `Runtime.Tests` (xunit v2 + Akka.TestKit.Xunit2).
+- **Task 10 (D-7):** `AddOtOpcUaHealth()` takes NO args, called unconditionally at `Program.cs:365`. DON'T change its signature — register the LocalDb check unconditionally and return `Healthy` when LocalDb absent (ActiveNodeHealthCheck precedent). Health check classes: there are ZERO in-repo today; `Host/Health/` has only `HealthEndpoints.cs`. Meter allowlist is REAL and REQUIRED: `Host/Observability/ObservabilityExtensions.cs:30` `o.Meters = [OtOpcUaTelemetry.MeterName]` — add `LocalDbMetrics.MeterName` (from `ZB.MOM.WW.LocalDb.Replication`). Health check reads `ISyncStatus` + `IOptions<ReplicationOptions>`.
+- **Task 11:** copy the `TwoNodeClusterHarness` direct-host-build pattern, NOT WebApplicationFactory. Pins: `ILocalDb` singleton + `ReplicatedTables` == `["deployment_artifacts","deployment_pointer"]`; `IDeploymentArtifactCache`→concrete; `ISyncStatus` default-OFF (`Connected==false`); admin-only graph has NO `ILocalDb` + doesn't demand `LocalDb:Path`; health check registered. Set `OTOPCUA_ROLES` per case; `LocalDb:Path`→temp file, `ClearAllPools`+delete triplet in cleanup.
+- **Task 12:** harness copied from `~/Desktop/ScadaBridge/tests/.../LocalDbSitePairHarness.cs` + `~/Desktop/scadaproj/ZB.MOM.WW.LocalDb/tests/.../Convergence/ConvergenceFixture.cs`. Both nodes init via PRODUCTION `LocalDbSetup.OnReady`. Real loopback Kestrel h2c through the REAL interceptor. DBs as pre-constructed singletons. Positive control: comment out both `RegisterReplicated`, confirm scenarios 1–3 red, restore (don't commit red).
+- **Task 13 (D-8):** NO host node has a writable volume today — must ADD named volumes. `docker-dev/docker-compose.yml` services: `central-1/2` (admin,driver, MAIN), `site-a-1/2` (driver, SITE-A), `site-b-1/2` (driver, SITE-B). Env style `Section__Key`. `9001` free container-internal. Enable replication on **site-a pair only** (a-1 initiator w/ PeerAddress, a-2 passive, byte-identical ApiKey, MaxBatchSize=16). site-b stays OFF = default-OFF pin. Validate `docker compose config`; DON'T bring rig up.
+- **Task 15:** baseline pre-existing test failures FIRST (`git stash` → run full `dotnet test` → unstash), report deltas only. **KNOWN intermittent:** one `Runtime.Tests` failure seen ~3× across runs (mine + subagent's), never reproduced under trx logger, NOT one of the new tests — investigate/baseline here.
+- **Warnings-as-errors** across src + most test projects. Pre-existing CS0618/xUnit1051 warnings exist ONLY in `Client.Shared*` (which don't set TreatWarningsAsErrors) — not mine, ignore.
+- **SQLitePCLRaw:** no pin needed — LocalDb 0.1.1 nuspec floors `lib.e_sqlite3` at 2.1.12 (CVE-fixed). Confirmed.
+
+## Follow-ups logged (NOT in scope, don't action without asking)
+
+- `Polly.Core` in `Configuration.csproj` now orphaned (ResilientConfigReader was its only real consumer). Left in place — recorded in recon §7.3b.
+- Pre-existing: `TryRecoverFromStale` marks Applied w/o reconciling drivers (recon §3.5); `Install-Services.ps1` gives driver-only nodes no `ASPNETCORE_URLS` (recon §6.4, worked around by D-6).
+
+## Verify-anything-quick
+
+Full build: `dotnet build ZB.MOM.WW.OtOpcUa.slnx` (expect 0 errors). LocalDb tests:
+`dotnet test tests/Server/ZB.MOM.WW.OtOpcUa.Host.IntegrationTests --filter "FullyQualifiedName~LocalDb"` and
+`dotnet test tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests --filter "FullyQualifiedName~ArtifactCache|FullyQualifiedName~BootFromCache"`.
@@ -0,0 +1,617 @@
+# LocalDb Phase 1 — Task 0 Recon Findings
+
+**Date:** 2026-07-20
+**Branch:** `feat/localdb-phase1` (based on `master`)
+**Plan:** `docs/plans/2026-07-20-localdb-adoption-phase1.md`
+**Design authority:** `~/Desktop/scadaproj/docs/plans/2026-07-20-otopcua-localdb-design.md`
+
+All `file:line` citations are against the branch base commit.
+
+---
+
+## Step 1 — Feed verification: PASS
+
+```
+$ dotnet package search ZB.MOM.WW.LocalDb --source dohertj2-gitea --format json
+ZB.MOM.WW.LocalDb              0.1.1
+ZB.MOM.WW.LocalDb.Contracts    0.1.1
+ZB.MOM.WW.LocalDb.Replication  0.1.1
+```
+
+All three present at **0.1.1**. No STOP. (Note: the local NuGet cache holds both `0.1.0` and `0.1.1`
+— pin exactly `0.1.1` so a stale cache cannot win.)
+
+---
+
+## Step 3 — STOP conditions: NONE TRIGGERED
+
+| STOP condition | Verdict |
+|---|---|
+| Artifact apply path cannot take a post-apply hook without restructuring the actor | **Clear** — `ApplyAndAck` has a clean insertion point (§2.2) |
+| `DeploymentId` / cluster identity are not stable strings/GUIDs | **Clear** — both are stable strings, but cluster identity is **not resolvable at boot**; see D-1 |
+| LiteDB LocalCache is referenced by live code | **Clear** — zero live-code references (§7) |
+
+Three STOP conditions clear. **Eight deviations** from the plan's stated assumptions are recorded in
+§9 — four of them (D-1, D-3, D-5, D-6) change the work materially.
+
+---
+
+## 1. Deploy fetch path
+
+### 1.1 Blob-load sites — there are **five** `CreateDbContext()` calls, not two
+
+| Line | Method | Purpose |
+|---|---|---|
+| `DriverHostActor.cs:513` | `Bootstrap()` | `NodeDeploymentStates` + `Deployments` at PreStart |
+| `DriverHostActor.cs:1472` | `ReconcileDrivers(DeploymentId)` | **loads `ArtifactBlob`** |
+| `DriverHostActor.cs:1543` | `PushDesiredSubscriptions(DeploymentId)` | **loads `ArtifactBlob` again** |
+| `DriverHostActor.cs:2000` | `TryRecoverFromStale()` | latest `Sealed` deployment (id + hash only, no blob) |
+| `DriverHostActor.cs:2029` | `UpsertNodeDeploymentState(...)` | writes `NodeDeploymentState` |
+
+`DriverHostActor.cs:1472-1476`:
+```csharp
+using var db = _dbFactory.CreateDbContext();
+blob = db.Deployments.AsNoTracking()
+    .Where(d => d.DeploymentId == deploymentId.Value)
+    .Select(d => d.ArtifactBlob)
+    .FirstOrDefault() ?? Array.Empty<byte>();
+```
+`:1543-1547` is byte-identical apart from the local. **The same blob is read twice per apply.**
+
+### 1.2 Artifact runtime type — there is no instance type
+
+`DeploymentArtifact` (`DeploymentArtifact.cs:48`) is a **static parser class** over
+`ReadOnlySpan<byte>`. The blob is never materialised into an object graph.
+
+- Storage: `byte[]` — `Deployment.cs:29` `public byte[] ArtifactBlob { get; init; } = Array.Empty<byte>();`
+- Format: **UTF-8 JSON**, `JsonDocument.Parse` (`DeploymentArtifact.cs:66`, `:490`). Not MessagePack.
+- Leniency contract: empty/malformed blob → empty result, **never throws** (`:62`, `:537-541`).
+
+**Consequence for the cache:** we cache raw `byte[]`. No serializer coupling. Good.
+
+### 1.3 Identity types
+
+| Type | Definition | Shape |
+|---|---|---|
+| `DeploymentId` | `Commons/Types/DeploymentId.cs:3` — `readonly record struct DeploymentId(Guid Value)` | `ToString()` → `Value.ToString("N")`, 32 hex chars, **no hyphens** (`:10`) |
+| `RevisionHash` | `Commons/Types/RevisionHash.cs:8` — `readonly record struct RevisionHash(string Value)` | SHA-256 hex, **lowercase 64 chars**, no `0x`; empty invalid (`:3-6`) |
+
+Both are stable, filesystem/SQL-safe strings. Use `DeploymentId.ToString()` (the "N" form) as the
+`deployment_id` TEXT column value.
+
+---
+
+## 2. Post-apply point
+
+### 2.1 `ApplyAndAck` control flow — `DriverHostActor.cs:1413-1458`
+
+```
+1415  _applyingDeploymentId = deploymentId;
+1416  Become(Applying);
+1425  UpsertNodeDeploymentState(..., Applying, null)
+1427  try {
+1429      ReconcileDrivers(deploymentId);            // blob fetch #1 — SWALLOWS DB errors
+1430      _currentRevision = revision;
+1431      UpsertNodeDeploymentState(..., Applied, null);
+1432      SendAck(..., ApplyAckOutcome.Applied, null, correlation);
+1436      _opcUaPublishActor?.Tell(RebuildAddressSpace(...));
+1439      PushDesiredSubscriptions(deploymentId);    // blob fetch #2 — SWALLOWS DB errors
+1440      OtOpcUaTelemetry.DeploymentApplied.Add(1, "outcome"="ack");
+1441      _log.Info("applied deployment ...");
+1443  }
+1444  catch (Exception ex) { ...Failed ACK... }
+1452  finally { _applyingDeploymentId = null; Become(Steady); }
+```
+
+### 2.2 Where the cache write belongs
+
+**Immediately after `DriverHostActor.cs:1439`**, before `:1440` — but **wrapped in its own
+try/catch**. Reason: `:1432` already sent an `Applied` ACK to the coordinator. An unguarded cache
+write that throws would fall into the `catch` at `:1444` and send a *second*, contradictory
+`Failed` ACK for a deployment the fleet already believes is applied.
+
+### 2.3 Paths that must NOT write to the cache
+
+1. **`catch` at `:1444`** — any apply failure.
+2. **Idempotent short-circuit at `:1402-1409`** — `HandleDispatchFromSteady` returns early with an
+   `Applied` ACK when `_currentRevision == msg.RevisionHash`. `ApplyAndAck` is never entered and no
+   blob is read.
+3. **⚠ THE SILENT-DEGRADATION TRAP.** `ReconcileDrivers:1478-1483` and
+   `PushDesiredSubscriptions:1549-1553` catch DB failures, log a **warning**, and `return` **without
+   rethrowing**. `ApplyAndAck` therefore reaches `:1440` and declares success having applied **zero
+   drivers** when the blob load failed. Caching "whatever we read" would **persist an empty artifact
+   as a successful apply** — poisoning the boot-from-cache path with a config that starts no drivers.
+
+   **Mitigation (load-bearing):** the cache write must be gated on the blob having actually loaded
+   non-empty. Have `ReconcileDrivers` surface the loaded blob upward (a field or an out-param)
+   rather than re-reading it a third time, and skip the cache write when it is
+   `Array.Empty<byte>()`. This also removes the duplicate read noted in §1.1.
+
+4. **`RestoreApplied` (`:1514-1528`)** — the bootstrap replay path. Restoring from central; caching
+   here is harmless and arguably desirable, but it is a distinct seam. **Phase 1 scope: skip it.**
+5. **`TryRecoverFromStale` (`:1996-2022`)** — never reads the artifact at all (see §3.4).
+
+---
+
+## 3. Cold-boot path
+
+### 3.1 PreStart — `DriverHostActor.cs:415-436`
+
+Ctor already did `Become(Steady)` at `:411`. PreStart subscribes to topics, spawns the virtual-tag
+and scripted-alarm hosts, then calls `Bootstrap()` at `:435`.
+
+### 3.2 `Bootstrap()` — `DriverHostActor.cs:506-565` — **yes, it queries central SQL at boot**
+
+Two queries inside one `try`: latest `NodeDeploymentState` for self (`:514-518`), then the matching
+`Deployment` row (`:527-532`). Four outcomes: no prior deployments → Steady; `Applied` →
+`RestoreApplied` (`:544`); `Applying` orphan → `ApplyAndAck` replay (`:549`); `Failed` → Steady.
+
+### 3.3 **THE SEAM** — `DriverHostActor.cs:560-564`
+
+```csharp
+catch (Exception ex)
+{
+    _log.Warning(ex, "DriverHost {Node}: ConfigDb unreachable on bootstrap; entering Stale", _localNode);
+    Become(Stale);
+}
+```
+
+**This is the exact point where "central fetch failed at boot" is known.** The cache fallback goes
+between `:562` and `:563`: attempt a local-cache load, and only `Become(Stale)` if the cache is also
+a miss.
+
+⚠ The catch also fires if the *second* query throws after the first succeeded, so `latest` is not in
+scope-valid state from the catch. **The cache must be self-describing** — it must carry its own
+`DeploymentId` + `RevisionHash`, because at this seam the actor has no idea what it should be
+restoring. The planned `deployment_pointer` shape already satisfies this.
+
+### 3.4 The `Stale` state — `DriverHostActor.cs:1343-1379`
+
+`ReconnectInterval = 30s` (`:55`), retry timer started at `:1378`.
+
+The dispatch-ignore at **`:1345-1348`** discards `DispatchDeployment` entirely — no ACK, no
+buffering (contrast `Applying:599` which does `Self.Forward(msg)`). A Stale node looks like a
+timeout to the coordinator. Phase 1 does **not** change this (per design §3.3: a *new* deployment
+still requires central).
+
+`RouteNodeWrite` fast-fails at `:1359-1360` with `"driver host stale (config DB unreachable)"`.
+
+### 3.5 Pre-existing gap worth recording (not Phase 1 scope)
+
+`TryRecoverFromStale` (`:1996-2022`) sets `_currentRevision` and marks `Applied` **without calling
+`ReconcileDrivers` or `PushDesiredSubscriptions`** — documented at `:1692-1695` and `:1706`. A
+Stale-recovered node reports Applied while running **zero drivers**, and
+`HandleDispatchFromSteady:1402` then short-circuits on revision match. Boot-from-cache largely
+neutralises this in practice, but the bookkeeping remains optimistic. **Logged as a follow-up, not
+fixed here.**
+
+### 3.6 `DbHealthProbeActor`
+
+**No interaction with `DriverHostActor` whatsoever.** Spawned as a sibling
+(`ServiceCollectionExtensions.cs:243-246`), consumed only by `OpcUaPublishActor`
+(`OpcUaPublishActor.cs:105`, `:256`, `:528`, `:543-544`). `DriverHostActor` runs its own independent
+30s `retry-db` timer. If running-from-cache should later influence OPC UA ServiceLevel,
+`OpcUaPublishActor`'s DB-health seam is the precedent to mirror.
+
+---
+
+## 4. Cluster identity — **the one real design problem (see D-1)**
+
+**There is no `ClusterId` field on `DriverHostActor` and no accessor for it.** The actor knows only
+`_localNode` (`DriverHostActor.cs:61`, type `Commons.Types.NodeId`, aliased at `:28`).
+
+`ClusterId` is resolved **per-artifact**, by `DeploymentArtifact.ResolveClusterScope(blob, nodeId)`
+(`DeploymentArtifact.cs:485-516`) — it scans the artifact's `Nodes[]` array for a matching `NodeId`
+and reads that element's `ClusterId`. Types: `ClusterScope` (`:46`), `ClusterFilterMode` (`:28`).
+
+`IClusterRoleInfo` (`Commons/Interfaces/IClusterRoleInfo.cs:12`) exposes `LocalNode`, `LocalRoles`,
+`HasRole`, `MembersWithRole`, `RoleLeader`, `RoleLeaderChanged` — **no `ClusterId`**.
+`docker-dev/docker-compose.yml` has `Cluster__Hostname`/`Port`/`Roles`/`SeedNodes` — **no
+`Cluster__ClusterId`**. The `ClusterNode` entity
+(`Configuration/Entities/ClusterNode.cs:7,10`) carries both, but lives in central SQL — exactly
+what is unreachable at the seam that needs it.
+
+> **The bind:** the design keys the cache by `ClusterId` so a replicated pair shares one cache
+> entry. But `ClusterId` is only discoverable *from a blob you already have* or *from central SQL*.
+> At the §3.3 boot-failure seam we have neither.
+
+**Resolution adopted (D-1):** keep `cluster_id` as the `deployment_pointer` PK — pair sharing is the
+whole point of replication and must not be given up. Resolve it at each end as follows:
+
+- **Write path** (`ApplyAndAck`, §2.2): call `DeploymentArtifact.ResolveClusterScope(blob, nodeId)`
+  on the blob just applied. `ClusterFilterMode.ScopeTo` → use its `ClusterId`. `None` (single-cluster
+  artifact) or `Suppress` → fall back to the literal `"__single"` sentinel, matching the actor's own
+  existing degenerate-case convention at `:1827-1830`.
+- **Read path** (boot seam, §3.3): we cannot compute the key, so **do not key the read**. Select the
+  single `deployment_pointer` row, ordered by `applied_at_utc DESC`, `LIMIT 1`. A node belongs to
+  exactly one cluster and its pair peer replicates the same cluster's row, so the table holds one
+  row in every real topology. If more than one row is present (a node was re-homed between
+  clusters), take the newest and **log a warning naming both cluster ids** — an operator-visible
+  signal rather than a silent wrong-config boot.
+- Optional escape hatch: honour a `Cluster:ClusterId` config key when present. **Deferred** — not
+  needed for the rig, and adding a required key contradicts the design's "storage ships
+  unconditionally" posture.
+
+This preserves the replication payoff (design §3.3) and the schema exactly as specified, and
+confines the change to the read query's `WHERE` clause.
+
+---
+
+## 5. `DriverHostActor` construction — the `Props` expression tree
+
+### 5.1 The factory — `DriverHostActor.cs:326-346`
+
+`static Props(...)` takes **16 parameters**, 14 optional, and forwards them **fully positionally**
+into `Akka.Actor.Props.Create(() => new DriverHostActor(...))` at **`:343-346`**. Ctor at
+`:375-412`, assignments `:393-408`.
+
+> ⚠ Six `IActorRef?` parameters and three interface-typed parameters mean many mis-bindings are
+> **type-compatible and therefore compile clean**. Callers use *named* arguments (safe); the
+> internal forwarding at `:343-346` is *positional* (unsafe).
+>
+> **Rule for Task 7: append the new parameter LAST in the `Props` signature, LAST in the ctor
+> signature, and LAST in the positional forwarding list at `:346`. Change nothing else.**
+
+### 5.2 Construction sites — **27 total** (1 production + 26 test)
+
+**Production (1):** `Runtime/ServiceCollectionExtensions.cs:332`, inside `WithOtOpcUaRuntimeActors`
+(`:193`); registered as `DriverHostActorKey` (`:344`). All args named except the first three. Does
+not pass `virtualTagHostOverride`, `scriptedAlarmHostOverride`, or `driverMemberCountProvider`.
+
+`WithOtOpcUaRuntimeActors` callers: `Host/Program.cs:331`,
+`Host.IntegrationTests/TwoNodeClusterHarness.cs:398`, `ServiceCollectionExtensionsTests.cs:42,144`.
+
+**Tests (26)**, all in `tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests/`:
+
+| File | Lines |
+|---|---|
+| `Drivers/DriverHostActorTests.cs` | 28, 60, 81, 118, 143, 189 |
+| `Drivers/DriverHostActorReconcileTests.cs` | 37, 59, 90, 119, 156, 193 |
+| `Drivers/DriverHostActorDiscoveryTests.cs` | 385, 671, 748, 1023 |
+| `Drivers/DriverHostActorWriteRoutingTests.cs` | 148, 208 |
+| `Drivers/DriverHostActorPrimaryGateTests.cs` | 228, 247 |
+| `Drivers/DriverHostActorVirtualTagTests.cs` | 44, 76 |
+| `Drivers/DriverHostActorNativeAlarmTests.cs` | 350 |
+| `Drivers/DriverHostActorNativeAlarmAckRoutingTests.cs` | 126 |
+| `Drivers/DriverHostActorProbeResultDropTests.cs` | 66 |
+| `Drivers/DriverHostActorHistoryWriterTests.cs` | 59 |
+| `Drivers/DiscoveryInjectionEndToEndTests.cs` | 219 |
+| `VirtualTags/DependencyMuxActorTests.cs` | 139 |
+
+No site calls `Props.Create<DriverHostActor>()` or `new DriverHostActor(...)` directly — the only
+`new DriverHostActor` in the tree is inside the factory at `:343`. Because the new parameter is
+optional and appended last, **no test site should need editing.**
+
+### 5.3 Status object for the running-from-cache signal
+
+`NodeDiagnosticsSnapshot` (`Commons/Interfaces/NodeDiagnosticsSnapshot.cs:17-22`) — built in
+`HandleGetDiagnostics` (`DriverHostActor.cs:1381-1398`), a positional record of
+`(NodeId, RevisionHash? CurrentRevision, IReadOnlyList<DriverInstanceDiagnostics> Drivers, DateTime AsOfUtc)`.
+`GetDiagnostics` is handled in **all three states** (`Steady:570`, `Applying:601`, `Stale:1349`), so
+a flag here is observable regardless of state. **This is the natural home for `RunningFromCache`**
+(append last to the record). Consumer: `IFleetDiagnosticsClient` → AdminUI.
+
+`IDriverHealthPublisher` (`:73`, defaulted `:402`) is **not** a fit — the host never calls it; it
+only passes it down to `DriverInstanceActor` children (`:1845`, `:1859`). Per-driver, not per-node.
+
+### 5.4 Async / side-effect IO convention
+
+The actor is **overwhelmingly synchronous-blocking on DB IO** — all five `CreateDbContext()` sites
+use `using var db = ...` with synchronous LINQ on the actor thread. No `async`/`await` in the file,
+no `Task.Run`.
+
+The single async pattern is `ContinueWith(..., TaskScheduler.Default).PipeTo(replyTo)` in
+`HandleRouteNodeWrite` (`:1188-1200`), with an explicit `Sender` capture before the continuation.
+
+**Recommendation for Task 7:** a **synchronous** cache write at the §2.2 point is *consistent with
+the file's existing style* and is correct there — the actor is mid-apply, holds `Applying`, and
+every other DB call on that path already blocks. A fire-and-forget `PipeTo(Self)` would need a
+handler registered in `Steady`, `Applying` **and** `Stale`, or it dead-letters after the
+`Become(Steady)` at `:1456`. **Prefer synchronous + try/catch.** (This deviates from the plan's
+"fire-and-forget"; see D-4.)
+
+`IWithTimers` is already implemented (`:50`, `:282`); `"retry-db"` key in use at `:1378`/`:2009`.
+
+---
+
+## 6. Host composition root
+
+### 6.1 Role flag — `Program.cs:47-50`
+
+```csharp
+var roles = RoleParser.Parse(Environment.GetEnvironmentVariable("OTOPCUA_ROLES"));
+var hasAdmin = roles.Contains("admin");
+var hasDriver = roles.Contains("driver");
+```
+Allowed roles: `admin`, `driver`, `dev` (`Cluster/RoleParser.cs:5-8`); unknown throws (`:25-27`).
+
+### 6.2 `hasDriver` branch — `Program.cs:131-310`
+
+Anchor for the new call: **`Program.cs:173-175`** `builder.Services.AddAlarmHistorian(...)`, inside
+the config-gated cluster at `:154-195`. Must land **before** `AddAkka` at `:314`.
+
+### 6.3 Pipeline — `Program.cs:368-404`
+
+`:383` `MapStaticAssets` · `:385-396` `if (hasAdmin) { ... }` · **`:398` `MapOtOpcUaHealth()`** ·
+`:399` `MapOtOpcUaMetrics()` · `:404` `RunAsync()`.
+
+⚠ **There is no `hasDriver` block in the pipeline half** — only `hasAdmin` is branched on. A
+driver-gated `app.Map*` is a new construct; it goes between `:396` and `:398`.
+
+`Program.cs:406-410` re-exports `public partial class Program`.
+
+### 6.4 Kestrel / URLs — **CONFIRMED: no Kestrel configuration exists**
+
+- `Program.cs:57` `builder.WebHost.UseStaticWebAssets();` — the **only** `builder.WebHost` call.
+- **Zero** `ConfigureKestrel` / `UseUrls` / `ListenAnyIP` / `UseKestrel` anywhere in `src/`.
+- Binding is exclusively via `ASPNETCORE_URLS`: `docker-compose.yml:173` (central-1) and `:240`
+  (central-2) set `http://+:9000`; `launchSettings.json:7` sets `http://localhost:9000`.
+
+Two traps for Task 5:
+
+1. ⚠ **`scripts/install/Install-Services.ps1:186`** (`$hostEnv += "ASPNETCORE_URLS=..."`) is inside
+   `if ($hasAdmin)` at `:185`. **A driver-only Windows-service node gets no `ASPNETCORE_URLS` at
+   all** and binds the ASP.NET default. The plan's parse-URLs-then-rebind snippet would re-bind
+   `http://+:9000` there — a port that node never listened on. The `?? "http://+:9000"` fallback in
+   the plan's snippet is therefore **wrong for driver-only nodes**; see D-6.
+2. ⚠ **`Host.IntegrationTests/TwoNodeClusterHarness.cs:331`** already calls
+   `builder.WebHost.UseKestrel(o => o.Listen(IPAddress.Parse(LoopbackHost), 0));`. Adding a
+   production `ConfigureKestrel` gives two competing explicit configurations in integration tests —
+   last-one-wins. The `syncPort > 0` gate keeps this dormant by default (harness sets no sync port),
+   but any harness that *does* set one will fight the port-0 binding.
+
+**Health route for smoke tests:** `/healthz` — liveness, runs no checks, always 200 while the
+process is up, `AllowAnonymous`. (`Health/HealthEndpoints.cs:48` → `MapZbHealth()`; routes from the
+`ZB.MOM.WW.Health` package.) Also `/health/ready`, `/health/active`, and `/metrics` (`Program.cs:399`).
+
+### 6.5 `SecretsRegistration` template — `Host/Configuration/SecretsRegistration.cs`
+
+Shape for `LocalDbRegistration` to mirror: `public static class` in
+`ZB.MOM.WW.OtOpcUa.Host.Configuration`; `public const string` section/key path constants; a
+`public static bool IsXEnabled(IConfiguration)` predicate using
+`GetValue(key, defaultValue: false)` (**default-deny**) that `Program.cs` can also call;
+`AddOtOpcUaX(this IServiceCollection, IConfiguration)` returning `IServiceCollection`, both args
+`ArgumentNullException.ThrowIfNull`-guarded; XML docs with `<remarks><para>` explaining *why* the
+gate is default-deny.
+
+Call-site precedent: `Program.cs:363` `AddOtOpcUaSecrets(...)`; predicate reused inside the `AddAkka`
+lambda at `Program.cs:323`.
+
+### 6.6 Telemetry meter allowlist — **EXISTS. Task 10 step 3 is REQUIRED, not conditional.**
+
+`Host/Observability/ObservabilityExtensions.cs:25-38`:
+```csharp
+return services.AddZbTelemetry(o =>
+{
+    o.ServiceName = "otopcua";
+    o.Meters = [OtOpcUaTelemetry.MeterName];          // <-- ObservabilityExtensions.cs:30
+    o.ActivitySources = [OtOpcUaTelemetry.ActivitySourceName];
+```
+
+`o.Meters` is a **strict allowlist** — `ZbTelemetryExtensions.cs:51-54` iterates it calling
+`metrics.AddMeter(name)`; **no wildcard support**. Anything unlisted is silently not exported.
+Single element today: `OtOpcUaTelemetry.MeterName` = `"ZB.MOM.WW.OtOpcUa"`
+(`Commons/Observability/OtOpcUaTelemetry.cs:19`).
+
+**Action:** add `LocalDbMetrics.MeterName` at `ObservabilityExtensions.cs:30`. This is exactly the
+omission the ScadaBridge live gate caught.
+
+### 6.7 Health registration — `Host/Health/HealthEndpoints.cs:19-41`
+
+`AddOtOpcUaHealth()` **takes no parameters** and is called **unconditionally** at `Program.cs:365`,
+outside both role blocks. Three `.AddTypeActivatedCheck<>` calls (`configdb`, `akka`,
+`admin-leader`); **no registration-time role gating exists** — `ActiveNodeHealthCheck` does runtime
+role scoping instead (returns `Healthy` when the node lacks the role).
+
+⚠ **There are zero `IHealthCheck` implementations in this repo** — all three come from the
+`ZB.MOM.WW.Health.*` packages (`Directory.Packages.props:124-126`, v0.1.0). A LocalDb check would be
+the **first health-check class in the tree**; `Host/Health/` holds only `HealthEndpoints.cs` today.
+
+**Consequence for Task 10:** driver-gating the new check requires changing
+`AddOtOpcUaHealth()`'s signature (add `bool hasDriver` or `IConfiguration`) and its `Program.cs:365`
+call site. **Preferred alternative:** follow the `ActiveNodeHealthCheck` precedent — register
+unconditionally and have the check return `Healthy` when LocalDb is not registered. That keeps the
+signature and matches the "default-OFF must not degrade a plain node" requirement for free. See D-7.
+
+### 6.8 Config files
+
+| File | Top-level sections |
+|---|---|
+| `appsettings.json` | `Serilog`, `Security`, `Secrets`, `ServerHistorian`, `ContinuousHistorization`, `AlarmHistorian`, `Deployment` |
+| `appsettings.driver.json` / `.admin.json` / `.admin-driver.json` / `.Development.json` | `Serilog`, `Security` only |
+
+Overlay selection: `Program.cs:67` sorts roles ordinally and joins with `-` → `admin,driver`
+becomes `appsettings.admin-driver.json`, added `optional: true` at `:70`; env vars (`:77`) and CLI
+args (`:78`) are re-appended after, so deployment overrides outrank the overlay.
+
+**`LocalDb` key search: CONFIRMED ABSENT.** Case-insensitive `localdb` across all `*.json`,
+`*.yml`, `*.ps1`, `*.csproj`, `*.props` matches only the two Phase-1/Phase-2 planning artifacts. No
+conflicting keys in any overlay or in `Install-Services.ps1`.
+
+**Placement convention:** each feature section opens with a `"_comment"` string then `"Enabled":
+false`; per-field caveats use sibling `"_<Field>Comment"` keys (`appsettings.json:34`, `:45`). Place
+`LocalDb` between `AlarmHistorian` (ends `:61`) and `Deployment` (`:62`).
+
+---
+
+## 7. LiteDB LocalCache — dormant, safe to delete
+
+### 7.1 Files (6) under `src/Core/ZB.MOM.WW.OtOpcUa.Configuration/LocalCache/`
+
+`ILocalConfigCache.cs`, `GenerationSnapshot.cs`, `StaleConfigFlag.cs`, `LiteDbConfigCache.cs`
+(also declares `LocalConfigCacheCorruptException` at `:128`), `GenerationSealedCache.cs`,
+`ResilientConfigReader.cs`. Single namespace `...Configuration.LocalCache`. The only two
+`using LiteDB;` statements in `src/` are `LiteDbConfigCache.cs:1` and `GenerationSealedCache.cs:1`.
+
+### 7.2 Reference classification — **no live-code references. NO STOP.**
+
+- **(c) live code elsewhere: ZERO.** Also confirms full dormancy: `SealedBootstrap` (referenced by
+  `docs/v2/v2-release-readiness.md:46`) has **zero hits** in `src/` and `tests/` — it no longer exists.
+- Two benign near-misses:
+  - `Configuration/Services/ILdapGroupRoleMappingService.cs:14` — the string `ResilientConfigReader`
+    inside an **XML doc comment**. Prose only. Needs a comment edit or the doc goes stale.
+  - `Configuration/ZB.MOM.WW.OtOpcUa.Configuration.csproj:29` — `<PackageReference Include="LiteDB"/>`,
+    the only one in the repo.
+- Dozens of `LocalConfigCacheCorruptException` hits under `src/**/bin/**/*.xml` are **generated doc
+  build artifacts** (`GenerateDocumentationFile=true`), not source.
+
+### 7.3 ⚠ Test-file drift — the plan's delete list is incomplete
+
+Plan `…phase1.md:484-485` names only `GenerationSealedCacheTests.cs` and
+`ResilientConfigReaderTests.cs`. Actual test files in
+`tests/Core/ZB.MOM.WW.OtOpcUa.Configuration.Tests/`:
+
+| File | Status |
+|---|---|
+| `GenerationSealedCacheTests.cs` | in plan ✅ |
+| `ResilientConfigReaderTests.cs` | in plan ✅ — note `StaleConfigFlagTests` is co-located here at `:323` |
+| **`LiteDbConfigCacheTests.cs`** | **MISSING from the plan** — will fail to compile if the source is deleted (`:125` calls `new LiteDB.LiteDatabase(...)` directly) |
+
+See D-3.
+
+### 7.3b Outcome (Task 9, executed 2026-07-20)
+
+Deleted: the 6 `LocalCache/` sources and **all three** test files (including
+`LiteDbConfigCacheTests.cs`, which the plan omitted — D-3). `LiteDB` removed from both
+`Configuration.csproj` and `Directory.Packages.props`. The stale XML-doc reference at
+`ILdapGroupRoleMappingService.cs:14` was rewritten to state the present truth (no fallback exists;
+reviving it means an admin-side cache on LocalDb, not restoring the old pipeline) rather than
+deleted, per the DoD's "explanatory prose may remain". Configuration tests: 92/92 green.
+
+**Follow-up found while executing:** `Polly.Core` in `Configuration.csproj` is now orphaned too —
+`ResilientConfigReader` was its only real consumer in that project (remaining `Polly` mentions are
+comments). Left in place deliberately: removing it is outside Task 9's scope and could break a
+consumer relying on the transitive flow. Worth a separate cleanup.
+
+### 7.4 Package removal
+
+- `PackageReference`: `Configuration.csproj:29` — only consumer.
+- `PackageVersion`: `Directory.Packages.props:35` — `LiteDB` `5.0.21`.
+
+Both safe to delete; no transitive consumer.
+
+---
+
+## 8. Test projects, rig, packages
+
+### 8.1 Test project layout
+
+| Question | Answer |
+|---|---|
+| `tests/Server/ZB.MOM.WW.OtOpcUa.Host.Tests/` | **DOES NOT EXIST** — there is no Host *unit*-test project at all |
+| Closest Host project | `Host.IntegrationTests` — despite the name it carries plenty of pure unit tests (`LdapOptionsValidatorTests`, `ServerHistorianOptionsValidatorTests`, `ResilienceInvokerFactoryRegistrationTests`, …) |
+| `tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests/` | **EXISTS** |
+| DriverHostActor tests | `Runtime.Tests/Drivers/` — 11 `DriverHostActor*Tests.cs` files. **xunit v2** (`xunit` 2.9.3), references **`Akka.TestKit.Xunit2`** ✅ |
+| `Host.IntegrationTests` xunit version | **xunit.v3** 1.1.0; SDK `Microsoft.NET.Sdk.Web` |
+
+`Directory.Packages.props` documents that AdminUI.Tests / ControlPlane.Tests / **Runtime.Tests** are
+the three xunit-v2 holdouts, held there by `Akka.TestKit.Xunit2` (verified 2026-07-13: no xunit.v3
+Akka TestKit exists). This matches the design's "actor tests live in an xunit2 TestKit project".
+
+### 8.2 ⚠ `WebApplicationFactory<Program>` is **deliberately not used** — Task 11 must be rewritten
+
+The only mention of the type in the entire `tests/` tree is a comment explaining why it is avoided:
+
+`Host.IntegrationTests/TwoNodeClusterHarness.cs:48`
+```
+/// <para>Why not <c>WebApplicationFactory&lt;Program&gt;</c>? Program.cs reads <c>OTOPCUA_ROLES</c> ...
+```
+
+The actual pattern builds the host directly — `TwoNodeClusterHarness.cs:329`:
+```csharp
+var builder = WebApplication.CreateBuilder(new WebApplicationOptions { Args = [] });
+```
+`Microsoft.AspNetCore.Mvc.Testing` is still referenced (csproj `:15`) but only for transitive
+test-host plumbing. **Copy `TwoNodeClusterHarness`, not `WebApplicationFactory`.** See D-5.
+
+`Host.IntegrationTests` also has its own `docker-compose.yml` (sql `14331`, ldap `3894`) gated by
+`DockerFixtureAvailability.cs`.
+
+### 8.3 docker-dev rig topology — plan's site-a/site-b assumption is **correct**
+
+Single Akka mesh (`otopcua`), seeded by `central-1`. Tenant separation is by `ServerCluster.ClusterId`
+rows (MAIN / SITE-A / SITE-B) inside **one shared ConfigDb** — not separate meshes.
+
+| Service | Roles | Cluster |
+|---|---|---|
+| `central-1`, `central-2` | `admin,driver` | MAIN |
+| `site-a-1`, `site-a-2` | `driver` | SITE-A |
+| `site-b-1`, `site-b-2` | `driver` | SITE-B |
+| `sql`, `migrator`, `cluster-seed`, `traefik` | — | infra |
+
+**There is no admin-only service** — the "admin" nodes are fused `admin,driver`. All six host nodes
+share the `&otopcua-host` YAML anchor.
+
+⚠ **NO HOST NODE HAS A WRITABLE VOLUME.** The only `volumes:` in the file are `sql` →
+`otopcua-mssql-data`, plus two read-only binds (`./seed:ro`, `./traefik-dynamic.yml:ro`). All six
+nodes write to the container's ephemeral layer, destroyed on recreate. This is already an accepted
+pattern (per-container `Secrets:SqlitePath=otopcua-secrets.db`, replicated over Akka rather than
+persisted). **Task 13 must add six named volumes** — there is nothing to piggyback on. See D-8.
+
+**Env style: confirmed double-underscore `Section__Key`**, with array indices and dictionary keys as
+a third segment (`Cluster__SeedNodes__0`, `Security__Ldap__GroupToRole__ReadOnly`). Exceptions that
+are plain SCREAMING_SNAKE (read directly, not config-bound): `OTOPCUA_ROLES`,
+`ZB_SECRETS_MASTER_KEY`, `GALAXY_MXGW_API_KEY`, `OTOPCUA_CONFIG_CONNECTION`, `ASPNETCORE_URLS`.
+
+**Ports.** Host-published: `14330`→sql, `4840`-`4845`→the six nodes' OPC UA, `9200`→traefik web,
+`8089`→traefik dashboard. Container-internal on every node: `4053` (Akka remoting), `9000`
+(Kestrel), `4840` (OPC UA). Also reserved on this machine: `14331`/`3894` (Host.IntegrationTests
+compose), `80`/`8080` (sibling scadabridge/scadalink stack), `10.100.0.35:3893` (shared GLAuth).
+
+**`9001` (the plan's choice) is free** container-internal and need not be published. ✅
+
+### 8.4 Package versions — `Directory.Packages.props`
+
+| Package | Version | Line |
+|---|---|---|
+| `Grpc.Core.Api` | 2.76.0 | 32 |
+| `Grpc.Net.Client` | 2.76.0 | 33 |
+| **`Grpc.AspNetCore`** | **NOT PRESENT** | — |
+| `Google.Protobuf` | 3.34.1 | 31 |
+| `Microsoft.Data.Sqlite` | 10.0.7 | ~55 |
+| `SQLitePCLRaw.bundle_e_sqlite3` | 2.1.12 | ~108 |
+| `LiteDB` | 5.0.21 | 35 |
+
+Both Grpc floors and the Protobuf floor are already satisfied — **no bumps needed**, only the new
+`Grpc.AspNetCore` entry (use 2.76.0 to match the train; watch for NU1605/NU1608 if it wants a
+Protobuf newer than the pinned 3.34.1).
+
+⚠ **`SQLitePCLRaw` is a surgical direct pin, not a transitive one.**
+`CentralPackageTransitivePinningEnabled` is deliberately **off** (it breaks the Roslyn version
+split). The 2.1.12 pin is promoted by a **direct `PackageReference` in `Core.AlarmHistorian`**
+(`Core.AlarmHistorian.csproj:15` + `:21`) — today the only Sqlite consumer in `src/`.
+
+> **Any new project that pulls `Microsoft.Data.Sqlite` MUST also take a direct
+> `<PackageReference Include="SQLitePCLRaw.bundle_e_sqlite3"/>`,** or it silently resolves the
+> vulnerable 2.1.11 native bundle. This applies to **Host** and **Runtime** (both gain `ZB.MOM.WW.LocalDb`,
+> which depends on `Microsoft.Data.Sqlite`) and to every test project that builds a real `ILocalDb`.
+> Copy the `Core.AlarmHistorian.csproj:15,21` pair exactly. The plan's Task 1 mentions
+> `SQLitePCLRaw.lib.e_sqlite3` "if the audit flags it" — the correct package is
+> **`bundle_e_sqlite3`**, and it is **required, not conditional**.
+
+---
+
+## 9. Deviations from the plan
+
+Recorded per the tasks.json `deviation` convention. **D-1, D-3, D-5, D-6 change the work
+materially.**
+
+| # | Plan says | Reality | Resolution |
+|---|---|---|---|
+| **D-1** | Cache keyed by `ClusterId`; "cluster identity" is a recon item with a STOP condition | `ClusterId` is stable, but **not resolvable at the boot seam** — it lives inside the artifact or in the unreachable central DB (§4) | Keep `cluster_id` as PK (pair sharing is the point). **Write:** resolve via `DeploymentArtifact.ResolveClusterScope`, `"__single"` sentinel for the degenerate case. **Read:** unkeyed `ORDER BY applied_at_utc DESC LIMIT 1`, warn if >1 row. No STOP. |
+| **D-2** | Cache write "fire-and-forget (`PipeTo`-style or guarded `Task.Run`)" | The actor has **no async DB IO at all**; a `PipeTo(Self)` needs handlers in all three states or it dead-letters after `Become(Steady)` (§5.4) | Synchronous write in its own try/catch at `:1439`. Matches the file's style; failure still cannot fail the apply. |
+| **D-3** | Task 9 deletes 2 test files | **3** test files reference the subsystem — `LiteDbConfigCacheTests.cs` is missing from the list (§7.3) | Delete all three. Also fix the stale XML-doc mention at `ILdapGroupRoleMappingService.cs:14`. |
+| **D-4** | Cache the artifact after a successful apply | `ReconcileDrivers`/`PushDesiredSubscriptions` **swallow** DB errors, so a "successful" apply can have loaded an **empty blob** and started zero drivers (§2.3) | Gate the write on a non-empty blob; surface the blob from `ReconcileDrivers` instead of a third read. **Load-bearing — without it the cache can be poisoned with an empty config.** |
+| **D-5** | Task 11 uses `WebApplicationFactory<Program>` | Deliberately **not used** in this repo; `TwoNodeClusterHarness.cs:48` documents why (Program.cs reads `OTOPCUA_ROLES` from the environment) (§8.2) | Rewrite Task 11 against the `TwoNodeClusterHarness` direct-host-build pattern. |
+| **D-6** | Task 5 re-binds `ASPNETCORE_URLS ?? "http://+:9000"` | `Install-Services.ps1:185-186` sets `ASPNETCORE_URLS` **only when `hasAdmin`** — the fallback would bind a driver-only node to a port it never served (§6.4) | Re-bind only when a URL is actually configured; when absent, add **only** the sync listener. Also note `TwoNodeClusterHarness.cs:331` already calls `UseKestrel(Listen(…, 0))`. |
+| **D-7** | Task 10 driver-gates the health check | `AddOtOpcUaHealth()` takes no args and is called unconditionally at `Program.cs:365`; no registration-time gating exists anywhere (§6.7) | Register unconditionally; return `Healthy` when LocalDb is absent — the `ActiveNodeHealthCheck` precedent. Avoids a signature change and satisfies "default-OFF must not degrade a plain node". |
+| **D-8** | Task 13 "existing data mount" | **No host node has any writable volume** (§8.3) | Add six named volumes. Note: `9001` is free container-internal. Meter allowlist (§6.6) is **required**, not conditional. |
+
+### Follow-ups logged, not fixed here
+
+1. **`TryRecoverFromStale` marks `Applied` without reconciling drivers** (§3.5) — pre-existing,
+   documented in-code at `:1692-1695`. Out of Phase 1 scope.
+2. **Duplicate blob read per apply** (`:1472` and `:1543`, §1.1) — D-4's fix removes one of them as a
+   side effect.
+3. **`Install-Services.ps1` gives driver-only nodes no `ASPNETCORE_URLS`** (§6.4) — pre-existing;
+   D-6 works around it rather than fixing it.
@@ -0,0 +1,76 @@
+# Issue #485 — live gate (docker-dev rig)
+
+> Verifies the two fixes for #485 — `OpcUaPublishActor` (master `c7f5b9cf`) and `DriverHostActor`
+> (master `5aad1e33`) — on the local `docker-dev` rig: 6 nodes, shared SQL, real Modbus fixture on
+> `10.100.0.35:5020`.
+>
+> **Safety rules followed**: all DB inspection + mutation via `sqlcmd` inside the SQL container; the
+> rig's Modbus fixture is read-only for this gate (no writes to the PLC sim).
+
+## Result
+
+**Both fixes verified, all three guards observed firing in production, with a live RED control that
+was not staged.** The gate also confirmed a **pre-existing** defect the fixes do not address — the node
+records `Applied` for a deployment it skipped (see "Finding" below).
+
+| # | Check | Result | Evidence |
+|---|---|---|---|
+| 1 | RED control — the bug in its natural habitat, unforced | ✅ | site-a-1 hit #485 during the *previous* gate's SQL flapping and had been serving an **empty address space for 34 minutes**: `failed to load artifact … rebuild becomes no-op` followed immediately by `applied plan (kind=PureRemove, added=0, removed=17, rebuild=True)`. Its 17 `ns=2` nodes were gone; a browse returned only the root `OtOpcUa` folder. Nothing was staged to produce this — it was already true on the pre-fix image. |
+| 2 | Rebuilt on the fixed image, the node recovers | ✅ | After `docker compose build` + `--force-recreate`, site-a-1 restored to `raw subtree materialised (containers=16, tags=1)` — 18 `ns=2` nodes. |
+| 3 | Address-space guard fires; nodes survive | ✅ | site-a-1, empty artifact: `OpcUaPublish: no usable artifact for deployment f4b9dd63… — KEEPING the currently served address space rather than tearing it down`. **No `PureRemove`.** Browse before vs after: 18 vs 18, `diff` **identical**. |
+| 4 | Reconcile guard fires; drivers survive | ✅ | `artifact for f4b9dd63… read back empty; skipping reconcile and keeping the 1 running driver(s)`, and the apply still reported `children=1`. Repeated on central-2 with a bigger blast radius: `keeping the 5 running driver(s)`, `children=5`. |
+| 5 | SubscribeBulk guard fires; **live values keep flowing** | ✅ | central-2, `artifact for 8c36a673… read back empty; skipping SubscribeBulk and keeping the live subscriptions`. The decisive proof is the value, not the log: `ns=2;s=pymodbus/plc/HR200X` read **56278 @ 06:59:51** before the induction, then **56336 @ 07:00:21** and **56354 @ 07:00:30** after it (induction at 07:00:07). The subscription was still delivering fresh Modbus data across the event. |
+| 6 | Positive control — a readable artifact still applies | ✅ | Immediately after the guards fired, a genuine deploy applied normally on both nodes: site-a-1 `AddRemoveMix, added=1, removed=1` + `SubscribeBulk pushed 1 references`; central-2 `AddRemoveMix, added=1, removed=1` + `SubscribeBulk pushed 5 references across 4 driver(s)`. The guards suppress the teardown, **not** deployment. |
+| 7 | Control — only the node that saw empty bytes took the guard path | ✅ | Of the six nodes, exactly **one** logged `read back empty` (the paused one); the other five read the real artifact before it was blanked and applied it normally. The induction window is what produced the condition, not a global change. |
+
+## How the failure was induced deterministically
+
+The original incident was a race (a transient ConfigDb blip landing between the apply and the artifact
+read). Racing it again would be unreliable, so the gate drives the **empty-bytes** branch instead — which
+is byte-for-byte what the code sees when the row cannot be read, and is the branch the driver-side guards
+key on (their *throw* paths already returned early before this work):
+
+1. `docker pause` the target node, freezing it mid-cluster.
+2. `POST /api/deployments` — the deployment seals and dispatches while the node cannot process it.
+3. `UPDATE Deployment SET ArtifactBlob = 0x WHERE DeploymentId = <new>`.
+4. `docker unpause` — the node now processes the dispatch and reads an empty artifact.
+
+The pause measured **<1s** on both runs, well inside `acceptable-heartbeat-pause = 10s` and SBR's
+`stable-after = 15s`, so the node was never flagged unreachable and no failover was triggered.
+
+## Finding — the node records `Applied` for a deployment it skipped (pre-existing, NOT fixed here)
+
+Both guards leave the node running its previous configuration, which is the intent. But `ApplyAndAck`
+advances `_currentRevision = revision` and writes `NodeDeploymentState = Applied` **before** it knows
+whether anything was applied — that assignment sits immediately after `ReconcileDrivers`, which returns
+`null` on both the (pre-existing) throw path and the new empty path:
+
+```
+[07:00:07 WRN] DriverHost central-2:4053: artifact … read back empty; skipping reconcile …
+[07:00:07 INF] DriverHost central-2:4053: applied deployment 8c36a673… (rev 03b33904…, children=5)
+```
+
+`NodeDeploymentState` for that deployment reads `Status = Applied` for central-2. The node now claims a
+revision whose configuration it never applied — and because `HandleDispatchFromSteady` short-circuits on
+a revision match (`dispatch matches current rev; immediate ACK`), **re-dispatching that same revision is
+a no-op**, so the node cannot self-heal. Only a later deployment with a *different* revision recovers it
+(check 6 confirms that path works).
+
+This is pre-existing — the throw path has always done it — and is strictly a reporting/convergence bug,
+not a data-plane one: the node keeps serving its last good configuration throughout. The honest fix is to
+ACK `Failed` and leave `_currentRevision` alone when the artifact could not be read, so the normal deploy
+retry heals it. Tracked separately rather than folded in here, because it changes deploy ACK semantics
+fleet-wide.
+
+## Addendum — issue #486 fix, live-gated (2026-07-21)
+
+The finding above is now fixed (`DriverHostActor.ApplyAndAck` fails the apply when `ReconcileDrivers`
+returns null) and gated on the same rig with the same induction.
+
+| # | Check | Result | Evidence |
+|---|---|---|---|
+| 8 | Regression — a normal deploy still ACKs Applied fleet-wide | ✅ | The change alters ACK semantics, so this is the risk that matters. A genuine deploy recorded `Status = Applied` on **all six** nodes. |
+| 9 | An unreadable artifact now ACKs Failed, with a reason | ✅ | central-2 recorded `Status = Failed` + `the deployment artifact could not be read (ConfigDb unreachable, or the row is missing/empty); nothing was applied`. The five nodes that read the real artifact recorded Applied — so the fleet view now distinguishes them. Pre-fix, all six claimed Applied. |
+| 10 | The revision is NOT advanced | ✅ | `apply of a855dd9e… FAILED — … Staying on revision 5bc0d9f3…` — the **previous** revision, not the dispatched `583122b7…`. This is what stops `HandleDispatchFromSteady` from short-circuiting a retry of that revision. |
+| 11 | The node keeps serving throughout (#485 still holds) | ✅ | The #485 guard fired first (`keeping the 5 running driver(s)`), and `ns=2;s=pymodbus/plc/HR200X` read **59603 @ 07:27:28**, live and current, after the Failed apply. Failing the apply reports the truth; it does not tear anything down. |
+| 12 | The node recovers on the next real deploy | ✅ | The following deployment applied on central-2 (`children=5`) and recorded Applied on all six nodes. |
@@ -0,0 +1,86 @@
+# LocalDb Phase 1 follow-ups — live gate (docker-dev rig)
+
+> Closes the two limitations left open by `2026-07-20-localdb-phase1-live-gate.md` (checks 4 and 8).
+> Rig: local `docker-dev/docker-compose.yml`, 6 nodes rebuilt from `fix/localdb-phase1-followups`.
+> site-a pair replicates; central + site-b stay default-OFF.
+>
+> **Safety rules followed** (same as the Phase 1 gate): all DB inspection via `docker cp` of the
+> `db`/`-wal`/`-shm` triplet, querying the copy — never host `sqlite3` on the live WAL file.
+
+## Result
+
+**Both follow-ups closed, and the gate found a third defect** — one that was *unreachable* until the
+first fix landed. Library `ZB.MOM.WW.LocalDb` went `0.1.1` → `0.1.2` → `0.1.3` in the course of this
+gate; both consumers (OtOpcUa, ScadaBridge) are pinned to `0.1.3`.
+
+| # | Check | Result | Evidence |
+|---|---|---|---|
+| 8 | Oplog stops growing on a default-OFF node | ✅ PASS | site-b-1 restarted twice with an unchanged cached artifact: `oplog_depth` **7 → 7 → 7**, `deployment_pointer.applied_at_utc` frozen at `05:34:58` across both — the re-cache was skipped outright. Repeated on the `0.1.3` build after a real deploy: **13 → 13**. Pre-fix this grew ~2 rows per restart forever, because a default-OFF node has no peer to ack and prune them. |
+| 8b | …but a genuinely new deployment still writes (positive control) | ✅ PASS | A real config change (renamed tag `SITEA-tag`) produced rev `822bdf34`, then `002c16b3`. site-b-1's oplog **7 → 10 → 13** and its pointer advanced each time. The skip suppresses *identical* re-writes only; it is not a dead cache-write path. |
+| 4 | A wiped node is back-filled by its peer, no new deploy, central down | ✅ PASS (was ⚠️ PARTIAL) | Precondition asserted first — site-a-1's oplog **0**, `needs_snapshot 0`: the exact state that used to make back-fill impossible. Then SQL stopped, site-a-2's LocalDb **volume destroyed**, container recreated. a-1 logged `Snapshot sent (as_of_seq 0, 4 rows)` — a line that could not appear on `0.1.1`. a-2 came back with pointer `SITE-A / 475df87a @ 03:09:12` (a-1's **original** timestamp, not a re-derived one), chunks 2, and a `__localdb_row_version` dump **byte-identical to a-1's**, carrying origin node ids `6812ca9c` and `935659a5` — the rebuilt node's own id appears nowhere, so the rows were replicated, not recreated. |
+| 4b | …and the back-filled node then boots from cache | ✅ PASS | With SQL still down, site-a-2 logged `RUNNING FROM CACHE — … booted deployment 475df87a… cached at 2026-07-21T03:09:12`, `raw subtree materialised (containers=16, tags=1)`. OPC UA browse of both nodes: **17 ns=2 nodes each, diff-identical** — the rebuilt node serves exactly what its healthy peer does, from a configuration it never applied itself and could not have fetched. |
+| 4c | The rebuilt node's OWN writes reach its peer | ✅ PASS **after a third fix** (see below) | On `0.1.2` this failed: a-1 held `last_applied_remote = 10` while the rebuilt a-2's oplog was seqs **1,2,3** and its `last_acked` stayed **0** — never accepted. On `0.1.3`, a-1 logs `Replication peer identity changed (ebb10854 -> c85d8b1d): the peer was rebuilt … Resetting the inbound watermark`, and after the next deploy a-1 shows `last_applied_remote = 3` / a-2 shows `last_acked = 3` with a drained oplog and identical row_versions. |
+
+## The third defect (the reason this gate was worth running)
+
+`0.1.2` made back-fill work, which for the first time let a rebuilt node be observed *writing*. It
+turned out its writes went nowhere.
+
+`last_applied_remote_seq` is a watermark in the **peer's** seq space, and a rebuilt peer is a new
+database whose oplog numbers from 1. Two independent bugs stacked, and fixing either alone leaves the
+data stuck:
+
+1. The healthy node kept advertising the **old** peer's watermark. The *sending* side seeds its pump
+   directly from that number (`_sentThruSeq`), so the rebuilt node skipped its entire oplog.
+   → the watermark (and the observed peer clock) is now reset when the peer's node id changes.
+   `last_acked_seq` is deliberately **not** reset: it describes our own oplog's pruned horizon and is
+   exactly what `0.1.2` keys the snapshot decision off — clearing it would switch back-fill back off.
+2. A peer claiming to have applied more of our stream than we have ever produced can only be
+   remembering a previous incarnation of *us*. → that claim is now rejected in favour of pumping from
+   the start; LWW makes the re-send harmless. This mirrors the clamp `RecordPeerAckAsync` already
+   applies to acks.
+
+Both were reproduced offline as a RED test before fixing
+(`SnapshotResyncTests.RebuiltPeer_OwnWritesReachTheHealthyNode_DespiteTheOldPeersWatermark`).
+
+**Why offline tests could not have found it first:** the wiped-peer scenario had no test because the
+scenario was believed impossible to recover from — it was a *documented limitation*, not a bug. The
+gate is what turned the limitation into a reproducible case, and the second defect only existed
+behind the first.
+
+## Unrelated finding (NOT a follow-up of this work — pre-existing; `lmxopcua` issue #485, since FIXED)
+
+While SQL was being stopped and started to drive check 4, site-b-1 took a deploy whose artifact load
+hit a transient ConfigDb error, and **emptied its served address space**:
+
+```
+[06:11:20 ERR] An error occurred using the connection to database 'OtOpcUa' on server 'sql,1433'.
+[06:11:20 WRN] OpcUaPublish: failed to load artifact for deployment 43d54397…; rebuild becomes no-op
+[06:11:20 INF] AddressSpaceApplier: applied plan (kind=PureRemove, added=0, removed=16, rebuild=True)
+```
+
+The log says "rebuild becomes no-op" and the applier then removed all 16 nodes — those two disagree.
+The cache layer behaved correctly and refused to store the bad artifact ("not caching deployment … its
+artifact was empty or could not be loaded, so it is not a usable last-known-good configuration"), and
+the node recovered fully on restart (`containers=16`). But a transient ConfigDb blip emptying the
+served address space instead of holding last-known-good is the same failure *class* as the Phase 1
+gate's check-3 defect. Untouched by this work — site-b-1 has replication off entirely — and induced by
+this gate's own SQL flapping.
+
+**Fixed** (issue #485): `OpcUaPublishActor.HandleRebuild` now treats an artifact it could not obtain as
+*no answer* rather than *an empty configuration*, and abandons the rebuild with the served address space
+(and `_lastApplied`) intact. Nothing legitimate produces a zero-length blob — an operator who really
+deletes everything still deploys a JSON document with empty arrays — so "no bytes" can only mean the read
+failed. The log excerpt above is now impossible: the `PureRemove` never runs, and the loader's own
+"the rebuild is abandoned" line is finally true. Covered by
+`OpcUaPublishActorRebuildTests.Rebuild_keeps_the_last_known_good_address_space_when_the_artifact_load_fails`,
+with a positive control proving a *readable* artifact that genuinely drops an equipment still tears its
+subtree down.
+
+The **driver-side half** of the same mistake was fixed alongside it: `DriverHostActor.ReconcileDrivers`
+and `PushDesiredSubscriptionsFromArtifact` read the artifact the same way, so empty bytes meant zero
+driver specs — `DriverSpawnPlanner` planned every running child for `StopChild` — and then an empty
+desired set dropped each surviving driver's live subscription handle. A node lost its entire field I/O
+and still ACKed Applied. Both now skip on empty. Covered by `DriverHostActorUnreadableArtifactTests`,
+whose absence assertion is calibrated by a control that observes the very same unsubscribe *arriving*
+inside the settle window (without it the assertion passed on a race).
@@ -380,6 +380,55 @@ polling the node.

 ---

+## Config secrets (`${secret:}` delivery)
+
+OtOpcUa never commits secret values to `appsettings*.json`. Every real secret is
+supplied at deploy time — either as a plain environment variable, or as a
+`${secret:<name>}` token backed by the shared **`ZB.MOM.WW.Secrets`** encrypted store.
+
+A pre-host expander (`SecretReferenceExpander.ExpandConfigurationAsync`, wired in
+`OtOpcUa.Host/Program.cs`) walks the assembled configuration and rewrites every
+`${secret:<name>}` token into its resolved plaintext **before** the host is built —
+so every downstream binder/validator (`AddZbSerilog`, `AddOtOpcUaConfigDb`, the first
+`ValidateOnStart`) sees resolved values. The store's key-encryption key (KEK) comes from
+the `ZB_SECRETS_MASTER_KEY` environment variable (`Secrets:MasterKey:Source=Environment`);
+the encrypted SQLite store lives at `Secrets:SqlitePath`.
+
+The expander is **fail-closed and section-agnostic**: a `${secret:<name>}` token whose
+secret is absent throws `SecretNotFoundException` at startup, regardless of which feature
+owns the key or whether that feature is enabled. Keys prefixed with `_` (comment keys) are
+skipped, so a `${secret:...}` example inside a `_…Comment` value is never resolved.
+
+The five config secrets and their canonical secret names:
+
+| Config key | Owner | Secret name |
+|---|---|---|
+| `Security:Jwt:SigningKey` | `JwtOptions` | `otopcua/jwt/signing-key` |
+| `Security:Ldap:ServiceAccountPassword` | `LdapOptions` | `otopcua/ldap/service-account-password` |
+| `Security:DeployApiKey` | `DeployApiEndpoints` | `otopcua/deploy/api-key` |
+| `ConnectionStrings:ConfigDb` | `AddOtOpcUaConfigDb` | `otopcua/sql/configdb-connstr` |
+| `ServerHistorian:ApiKey` | `ServerHistorianOptions` | `otopcua/historian/api-key` |
+
+**Delivery.** By default these are delivered as plain environment variables (e.g.
+`ServerHistorian__ApiKey=histgw_…`), never committed. To deliver one from the encrypted
+store instead, seed it once with the `secret` CLI (from `ZB.MOM.WW.Secrets`), then supply
+the token in place of the literal — via env var or a deployment appsettings overlay:
+
+```
+secret set otopcua/historian/api-key <value>       # seed the encrypted store first
+ServerHistorian__ApiKey='${secret:otopcua/historian/api-key}'
+```
+
+Only switch a value to a `${secret:}` token **after** the secret is seeded — an unseeded
+token fails the boot fail-closed. Do not commit the KEK (`ZB_SECRETS_MASTER_KEY`) or any
+secret value.
+
+For the production posture needed so every clustered node (admin, driver, and any
+fused role) resolves the same secrets from the same store, see
+[`docs/operations/2026-07-16-secrets-clustered-master-key.md`](operations/2026-07-16-secrets-clustered-master-key.md).
+
+---
+
 ## Troubleshooting

 ### Certificate trust failure
@@ -0,0 +1,293 @@
+using System.Globalization;
+using System.Text;
+
+namespace ZB.MOM.WW.OtOpcUa.Commons.Csv;
+
+/// <summary>
+///     A pure, allocation-lean RFC 4180 CSV reader with no file/stream I/O of its own — it consumes a
+///     <see cref="string"/> or a <see cref="TextReader"/> and yields rows of fields. This is the single
+///     CSV-reading authority in the tree; keep the RFC contract pinned here (and mirrored in
+///     <see cref="CsvWriter"/>) rather than re-deriving it at each call site.
+/// </summary>
+/// <remarks>
+///     <para><b>Faithful to RFC 4180.</b> The grammar handled:</para>
+///     <list type="bullet">
+///         <item>Fields are separated by the delimiter (default <c>','</c>); records are separated by
+///         newlines.</item>
+///         <item>A field may be quoted with double-quotes (<c>"</c>). A quoted field may contain the
+///         delimiter, CR, LF, and CRLF literally, and represents a literal double-quote by doubling it
+///         (<c>""</c> → <c>"</c>).</item>
+///         <item>An unquoted field runs literally up to the next delimiter or newline; leading and
+///         trailing spaces are preserved (RFC 4180 §2.4 — spaces are part of a field).</item>
+///         <item>CRLF, bare LF, and bare CR are all accepted as record terminators.</item>
+///     </list>
+///     <para><b>Empty-line policy.</b> Faithful to the RFC: a line with no characters yields a single row
+///     containing one empty field (<c>[""]</c>); it is NOT silently dropped. Callers that want blank lines
+///     skipped should filter the result (e.g. <c>rows.Where(r =&gt; r.Length &gt; 1 || r[0].Length &gt; 0)</c>).
+///     A trailing record terminator at end-of-input does NOT produce a phantom empty final row, and its
+///     absence does not lose the last row.</para>
+///     <para><b>Malformed-input policy.</b> This parser is <b>strict</b>. It throws
+///     <see cref="System.FormatException"/> (carrying a 1-based line/column position) for the malformed
+///     shapes RFC 4180 forbids: (1) a bare double-quote inside an otherwise-unquoted field (e.g.
+///     <c>ab"c</c>), (2) a stray character after a closing quote other than the delimiter or a newline
+///     (e.g. <c>"ab"c</c>), and (3) an unterminated quoted field at end-of-input. Strictness is deliberate
+///     — silent lenient recovery hides data-shape bugs in imported files.</para>
+/// </remarks>
+public static class CsvParser
+{
+    private const char Quote = '"';
+    private const char Cr = '\r';
+    private const char Lf = '\n';
+
+    /// <summary>
+    ///     Parses <paramref name="text"/> fully into rows of fields. Convenience wrapper over
+    ///     <see cref="Parse(TextReader,char)"/>; materialises the whole document.
+    /// </summary>
+    /// <param name="text">The CSV document. <c>null</c> is treated as empty.</param>
+    /// <param name="delimiter">The field separator (default comma).</param>
+    /// <returns>The rows, each an array of field values. Empty input yields zero rows.</returns>
+    /// <exception cref="System.FormatException">The input violates the strict RFC 4180 grammar.</exception>
+    public static IReadOnlyList<string[]> Parse(string? text, char delimiter = ',')
+    {
+        using var reader = new StringReader(text ?? string.Empty);
+        var rows = new List<string[]>();
+        foreach (var row in Parse(reader, delimiter))
+        {
+            rows.Add(row);
+        }
+
+        return rows;
+    }
+
+    /// <summary>
+    ///     Streams rows from <paramref name="reader"/> lazily — a single forward pass, one row
+    ///     materialised at a time. The reader is not disposed by this method.
+    /// </summary>
+    /// <param name="reader">The source. Read to end-of-input.</param>
+    /// <param name="delimiter">The field separator (default comma).</param>
+    /// <returns>A lazily-evaluated sequence of rows; each row is a freshly allocated field array.</returns>
+    /// <exception cref="System.ArgumentNullException"><paramref name="reader"/> is <c>null</c>.</exception>
+    /// <exception cref="System.ArgumentException"><paramref name="delimiter"/> is a quote, CR, or LF.</exception>
+    /// <exception cref="System.FormatException">The input violates the strict RFC 4180 grammar.</exception>
+    public static IEnumerable<string[]> Parse(TextReader reader, char delimiter = ',')
+    {
+        ArgumentNullException.ThrowIfNull(reader);
+        if (delimiter is Quote or Cr or Lf)
+        {
+            throw new ArgumentException("Delimiter must not be a double-quote, CR, or LF.", nameof(delimiter));
+        }
+
+        return Iterate(reader, delimiter);
+    }
+
+    private static IEnumerable<string[]> Iterate(TextReader reader, char delimiter)
+    {
+        var field = new StringBuilder();
+        var row = new List<string>();
+
+        // True once the current row has produced any field boundary or content — i.e. once we've seen a
+        // char that commits us to emitting at least one field. Reset to false right after a record
+        // terminator closes a row, so a trailing newline at EOF does NOT synthesise a phantom row.
+        var rowOpen = false;
+
+        // 1-based cursor, maintained for FormatException messages.
+        var line = 1;
+        var col = 0;
+
+        int read;
+        while ((read = reader.Read()) != -1)
+        {
+            var c = (char)read;
+            col++;
+
+            if (c == Quote)
+            {
+                if (field.Length != 0)
+                {
+                    throw new FormatException(
+                        $"Unexpected double-quote inside an unquoted field at line {line}, column {col}. " +
+                        "A field is quoted only when the quote is its first character.");
+                }
+
+                rowOpen = true;
+
+                // Consume the quoted body; the opening quote has been read.
+                ReadQuotedField(reader, field, ref line, ref col);
+
+                // A closing quote must be followed by the delimiter, a newline, or EOF.
+                var next = reader.Peek();
+                if (next == -1)
+                {
+                    row.Add(field.ToString());
+                    field.Clear();
+                    yield return row.ToArray();
+                    row.Clear();
+                    rowOpen = false;
+                    yield break;
+                }
+
+                var nc = (char)next;
+                if (nc == delimiter)
+                {
+                    reader.Read();
+                    col++;
+                    row.Add(field.ToString());
+                    field.Clear();
+                    continue;
+                }
+
+                if (nc is Cr or Lf)
+                {
+                    row.Add(field.ToString());
+                    field.Clear();
+                    ConsumeNewline(reader, ref line, ref col);
+                    yield return row.ToArray();
+                    row.Clear();
+                    rowOpen = false;
+                    continue;
+                }
+
+                throw new FormatException(
+                    $"Unexpected character '{nc}' after closing quote at line {line}, column {col + 1}. " +
+                    "A quoted field must be followed by a delimiter, a newline, or end-of-input.");
+            }
+
+            if (c == delimiter)
+            {
+                row.Add(field.ToString());
+                field.Clear();
+                rowOpen = true;
+                continue;
+            }
+
+            if (c is Cr or Lf)
+            {
+                row.Add(field.ToString());
+                field.Clear();
+                if (c == Cr && reader.Peek() == Lf)
+                {
+                    reader.Read();
+                }
+
+                line++;
+                col = 0;
+                yield return row.ToArray();
+                row.Clear();
+                rowOpen = false;
+                continue;
+            }
+
+            field.Append(c);
+            rowOpen = true;
+        }
+
+        // EOF: emit a trailing row only if content is pending. A clean terminator already cleared rowOpen.
+        if (rowOpen || field.Length != 0 || row.Count != 0)
+        {
+            row.Add(field.ToString());
+            yield return row.ToArray();
+        }
+    }
+
+    /// <summary>
+    ///     Reads the body of a quoted field into <paramref name="field"/>. The opening quote has already
+    ///     been consumed. On return the reader sits immediately after the closing quote.
+    /// </summary>
+    private static void ReadQuotedField(TextReader reader, StringBuilder field, ref int line, ref int col)
+    {
+        var openLine = line;
+        var openCol = col;
+
+        int read;
+        while ((read = reader.Read()) != -1)
+        {
+            var c = (char)read;
+            col++;
+
+            if (c == Quote)
+            {
+                if (reader.Peek() == Quote)
+                {
+                    reader.Read();
+                    col++;
+                    field.Append(Quote);
+                    continue;
+                }
+
+                return; // closing quote
+            }
+
+            if (c == Lf)
+            {
+                line++;
+                col = 0;
+            }
+
+            field.Append(c);
+        }
+
+        throw new FormatException(
+            $"Unterminated quoted field opened at line {openLine}, column {openCol}: reached end-of-input " +
+            "before the closing double-quote.");
+    }
+
+    /// <summary>Consumes a newline (CRLF, CR, or LF) whose first character has been peeked but not read.</summary>
+    private static void ConsumeNewline(TextReader reader, ref int line, ref int col)
+    {
+        var first = reader.Read();
+        if (first == Cr && reader.Peek() == Lf)
+        {
+            reader.Read();
+        }
+
+        line++;
+        col = 0;
+    }
+
+    /// <summary>
+    ///     Header-aware convenience: parses <paramref name="text"/> and maps every subsequent row onto the
+    ///     first (header) row's field names. Thin wrapper over <see cref="Parse(string,char)"/>.
+    /// </summary>
+    /// <param name="text">The CSV document; the first row is treated as the header.</param>
+    /// <param name="delimiter">The field separator (default comma).</param>
+    /// <returns>
+    ///     One dictionary per data row, keyed by header name (ordinal, case-sensitive). A row shorter than
+    ///     the header maps only the columns present; a column beyond the header's width is keyed by its
+    ///     0-based index rendered as a string. An empty document yields zero rows.
+    /// </returns>
+    /// <exception cref="System.FormatException">The input violates the strict RFC 4180 grammar, or the header contains a duplicate column name.</exception>
+    public static IReadOnlyList<IReadOnlyDictionary<string, string>> ParseWithHeader(string? text, char delimiter = ',')
+    {
+        var rows = Parse(text, delimiter);
+        if (rows.Count == 0)
+        {
+            return Array.Empty<IReadOnlyDictionary<string, string>>();
+        }
+
+        var header = rows[0];
+        var seen = new HashSet<string>(StringComparer.Ordinal);
+        foreach (var name in header)
+        {
+            if (!seen.Add(name))
+            {
+                throw new FormatException($"Duplicate header column name '{name}'.");
+            }
+        }
+
+        var result = new List<IReadOnlyDictionary<string, string>>(rows.Count - 1);
+        for (var i = 1; i < rows.Count; i++)
+        {
+            var cells = rows[i];
+            var map = new Dictionary<string, string>(cells.Length, StringComparer.Ordinal);
+            for (var c = 0; c < cells.Length; c++)
+            {
+                var key = c < header.Length ? header[c] : c.ToString(CultureInfo.InvariantCulture);
+                map[key] = cells[c];
+            }
+
+            result.Add(map);
+        }
+
+        return result;
+    }
+}
@@ -0,0 +1,142 @@
+using System.Text;
+
+namespace ZB.MOM.WW.OtOpcUa.Commons.Csv;
+
+/// <summary>
+///     A pure RFC 4180 CSV writer with no file/stream I/O of its own — it renders rows of fields to a
+///     <see cref="string"/> or a <see cref="TextWriter"/>. The inverse of <see cref="CsvParser"/>:
+///     <c>CsvParser.Parse(CsvWriter.WriteToString(rows))</c> reproduces <c>rows</c> exactly for any field
+///     content.
+/// </summary>
+/// <remarks>
+///     <para><b>Quote-on-demand.</b> A field is wrapped in double-quotes only when it must be — i.e. when
+///     it contains the delimiter, a double-quote, CR, or LF — and internal double-quotes are doubled
+///     (<c>"</c> → <c>""</c>). Fields that need no quoting are emitted verbatim, so ordinary values stay
+///     human-readable. Pass <c>quoteAllFields: true</c> to force every field quoted.</para>
+///     <para><b>Newline.</b> The record terminator defaults to CRLF (<c>\r\n</c>) per RFC 4180 and is
+///     configurable. No terminator is written after the final row (matching the parser's
+///     no-phantom-trailing-row contract, so a round-trip is exact).</para>
+/// </remarks>
+public static class CsvWriter
+{
+    private const char Quote = '"';
+    private const char Cr = '\r';
+    private const char Lf = '\n';
+
+    /// <summary>The RFC 4180 record terminator, <c>"\r\n"</c>. The default <c>newline</c> for every write.</summary>
+    public const string Crlf = "\r\n";
+
+    /// <summary>
+    ///     Renders <paramref name="rows"/> to a CSV string.
+    /// </summary>
+    /// <param name="rows">The rows to write; each inner sequence is one record's fields. A <c>null</c> field is written as empty.</param>
+    /// <param name="delimiter">The field separator (default comma).</param>
+    /// <param name="newline">The record terminator between rows (default CRLF). Not appended after the last row.</param>
+    /// <param name="quoteAllFields">When <c>true</c>, every field is quoted regardless of content.</param>
+    /// <returns>The CSV text. An empty <paramref name="rows"/> yields the empty string.</returns>
+    /// <exception cref="System.ArgumentNullException"><paramref name="rows"/> is <c>null</c>.</exception>
+    /// <exception cref="System.ArgumentException"><paramref name="delimiter"/> is a quote, CR, or LF.</exception>
+    public static string WriteToString(
+        IEnumerable<IEnumerable<string?>> rows,
+        char delimiter = ',',
+        string newline = Crlf,
+        bool quoteAllFields = false)
+    {
+        var sb = new StringBuilder();
+        using var writer = new StringWriter(sb);
+        Write(writer, rows, delimiter, newline, quoteAllFields);
+        return sb.ToString();
+    }
+
+    /// <summary>
+    ///     Writes <paramref name="rows"/> to <paramref name="writer"/>. The writer is not disposed or
+    ///     flushed by this method.
+    /// </summary>
+    /// <param name="writer">The destination.</param>
+    /// <param name="rows">The rows to write; each inner sequence is one record's fields. A <c>null</c> field is written as empty.</param>
+    /// <param name="delimiter">The field separator (default comma).</param>
+    /// <param name="newline">The record terminator between rows (default CRLF). Not appended after the last row.</param>
+    /// <param name="quoteAllFields">When <c>true</c>, every field is quoted regardless of content.</param>
+    /// <exception cref="System.ArgumentNullException"><paramref name="writer"/> or <paramref name="rows"/> is <c>null</c>.</exception>
+    /// <exception cref="System.ArgumentException"><paramref name="delimiter"/> is a quote, CR, or LF.</exception>
+    public static void Write(
+        TextWriter writer,
+        IEnumerable<IEnumerable<string?>> rows,
+        char delimiter = ',',
+        string newline = Crlf,
+        bool quoteAllFields = false)
+    {
+        ArgumentNullException.ThrowIfNull(writer);
+        ArgumentNullException.ThrowIfNull(rows);
+        if (delimiter is Quote or Cr or Lf)
+        {
+            throw new ArgumentException("Delimiter must not be a double-quote, CR, or LF.", nameof(delimiter));
+        }
+
+        var firstRow = true;
+        foreach (var row in rows)
+        {
+            if (!firstRow)
+            {
+                writer.Write(newline);
+            }
+
+            firstRow = false;
+
+            WriteRow(writer, row, delimiter, quoteAllFields);
+        }
+    }
+
+    private static void WriteRow(TextWriter writer, IEnumerable<string?> row, char delimiter, bool quoteAllFields)
+    {
+        ArgumentNullException.ThrowIfNull(row);
+
+        var firstField = true;
+        foreach (var field in row)
+        {
+            if (!firstField)
+            {
+                writer.Write(delimiter);
+            }
+
+            firstField = false;
+
+            WriteField(writer, field ?? string.Empty, delimiter, quoteAllFields);
+        }
+    }
+
+    private static void WriteField(TextWriter writer, string field, char delimiter, bool quoteAllFields)
+    {
+        if (!quoteAllFields && !NeedsQuoting(field, delimiter))
+        {
+            writer.Write(field);
+            return;
+        }
+
+        writer.Write(Quote);
+        foreach (var ch in field)
+        {
+            if (ch == Quote)
+            {
+                writer.Write(Quote); // double an internal quote
+            }
+
+            writer.Write(ch);
+        }
+
+        writer.Write(Quote);
+    }
+
+    private static bool NeedsQuoting(string field, char delimiter)
+    {
+        foreach (var ch in field)
+        {
+            if (ch == delimiter || ch == Quote || ch == Cr || ch == Lf)
+            {
+                return true;
+            }
+        }
+
+        return false;
+    }
+}
@@ -14,8 +14,16 @@ public sealed record DriverInstanceDiagnostics(
 /// Per-node diagnostics returned by <c>IFleetDiagnosticsClient</c>. Populated by the node's
 /// local <c>DriverHostActor</c> via a request/response over Akka.
 /// </summary>
+/// <param name="RunningFromCache">
+///     True when the node booted its configuration from the node-local artifact cache because the
+///     central ConfigDb was unreachable. Such a node looks entirely healthy — full address space,
+///     live values — but its configuration is frozen and no deployment can reach it, so the state
+///     needs to be explicitly visible rather than inferred. Defaults to false, which is also what
+///     every node that booted normally reports.
+/// </param>
 public sealed record NodeDiagnosticsSnapshot(
    NodeId NodeId,
    RevisionHash? CurrentRevision,
    IReadOnlyList<DriverInstanceDiagnostics> Drivers,
-    DateTime AsOfUtc);
+    DateTime AsOfUtc,
+    bool RunningFromCache = false);
@@ -17,6 +17,7 @@ namespace ZB.MOM.WW.OtOpcUa.Commons.Messages.Alerts;
 /// <param name="AlarmTypeName">OPC UA Part 9 condition subtype name — one of <c>LimitAlarm</c> / <c>DiscreteAlarm</c> / <c>OffNormalAlarm</c> / <c>AlarmCondition</c> (the base type, used as the default). The historian feed maps this onto the durable alarm-type column.</param>
 /// <param name="Comment">Operator-supplied comment on ack / confirm / comment transitions; <c>null</c> for engine-driven transitions (Activated / Cleared / Shelved / …) that carry no comment.</param>
 /// <param name="HistorizeToAveva">When <c>false</c>, the durable historian sink suppresses this transition (the live <c>alerts</c> fan-out is unaffected); <c>null</c> or <c>true</c> historize. <c>null</c> is the cross-version/rolling-restart case: an old-format message missing the field deserializes to <c>null</c> (CLR default for <c>bool?</c>) and is historized (safe default-on), matching the <c>AlarmTypeName</c> null-coalesce in <c>HistorianAdapterActor.Translate</c>. The producer (<c>ScriptedAlarmHostActor</c>) always sets a concrete <c>true</c>/<c>false</c>.</param>
+/// <param name="ReferencingEquipmentPaths">v3 Batch 4 (multi-notifier native alarms) — the (possibly empty) list of UNS equipment-folder paths (<c>Area/Line/Equipment</c>) that reference the alarm's backing raw tag. A native alarm is a SINGLE Part 9 condition materialised once at the raw tag (its <see cref="AlarmId"/> is the RawPath); the same condition fans events to every referencing equipment's UNS folder via SDK notifiers, and this list is carried so <c>/alerts</c> shows the one condition row with all its referencing equipment as display metadata. Empty for scripted alarms (they are per-equipment) and for a native alarm whose raw tag no equipment references. Defaults empty so every existing producer + rolling-restart deserialization keeps compiling / working.</param>
 public sealed record AlarmTransitionEvent(
    string AlarmId,
    string EquipmentPath,
@@ -28,4 +29,5 @@ public sealed record AlarmTransitionEvent(
    DateTime TimestampUtc,
    string AlarmTypeName = "AlarmCondition",
    string? Comment = null,
-    bool? HistorizeToAveva = null);
+    bool? HistorizeToAveva = null,
+    IReadOnlyList<string>? ReferencingEquipmentPaths = null);
@@ -0,0 +1,18 @@
+namespace ZB.MOM.WW.OtOpcUa.Commons.OpcUa;
+
+/// <summary>
+///     Which of the two v3 OPC UA namespaces a node lives in. Carried explicitly alongside a
+///     node's <c>s=</c> identifier at every address-space sink seam so the namespace is chosen at
+///     the call site, never parsed back out of the id string (explicit beats inferred).
+///     <see cref="V3NodeIds.NamespaceUri"/> maps each realm to its namespace URI.
+/// </summary>
+public enum AddressSpaceRealm
+{
+    /// <summary>The device-oriented Raw tree (Folder→Driver→Device→TagGroup→Tag); a node's
+    /// <c>s=</c> id is its <see cref="ZB.MOM.WW.OtOpcUa.Commons.Types.RawPaths">RawPath</see>.</summary>
+    Raw,
+
+    /// <summary>The equipment-oriented UNS tree (Area→Line→Equipment→signal); a node's <c>s=</c>
+    /// id is the slash-joined <c>Area/Line/Equipment[/EffectiveName]</c>.</summary>
+    Uns,
+}
@@ -16,6 +16,12 @@ namespace ZB.MOM.WW.OtOpcUa.Commons.OpcUa;
 /// <param name="Shelving">The shelving mode (ShelvingState): unshelved, one-shot, or timed.</param>
 /// <param name="Severity">OPC UA severity on the 1..1000 scale (the SDK <c>SetSeverity</c> input).</param>
 /// <param name="Message">The human-readable condition message (LocalizedText payload).</param>
+/// <param name="Quality">
+///     Quality of the condition's source data (Part 9 <c>ConditionType.Quality</c>). Carried so a
+///     comms-lost native source can report a non-<c>Good</c> condition instead of the accidentally-Good
+///     default (issue #477). It is a pure annotation — it never alters Active/Acked/Retain. Defaults to
+///     <see cref="OpcUaQuality.Good"/> so scripted-alarm callers (which stay Good in v1) need not supply it.
+/// </param>
 public sealed record AlarmConditionSnapshot(
    bool Active,
    bool Acknowledged,
@@ -23,7 +29,8 @@ public sealed record AlarmConditionSnapshot(
    bool Enabled,
    AlarmShelvingKind Shelving,
    ushort Severity,
-    string Message);
+    string Message,
+    OpcUaQuality Quality = OpcUaQuality.Good);

 /// <summary>
 ///     Commons-local mirror of the Core <c>ShelvingKind</c> enum so this assembly carries no
@@ -23,30 +23,44 @@ public sealed class DeferredAddressSpaceSink : IOpcUaAddressSpaceSink, ISurgical
        _inner = sink ?? NullOpcUaAddressSpaceSink.Instance;

    /// <inheritdoc />
-    public void WriteValue(string nodeId, object? value, OpcUaQuality quality, DateTime sourceTimestampUtc)
-        => _inner.WriteValue(nodeId, value, quality, sourceTimestampUtc);
+    public void WriteValue(string nodeId, object? value, OpcUaQuality quality, DateTime sourceTimestampUtc, AddressSpaceRealm realm)
+        => _inner.WriteValue(nodeId, value, quality, sourceTimestampUtc, realm);

    /// <inheritdoc />
-    public void WriteAlarmCondition(string alarmNodeId, AlarmConditionSnapshot state, DateTime sourceTimestampUtc)
-        => _inner.WriteAlarmCondition(alarmNodeId, state, sourceTimestampUtc);
+    public void WriteAlarmCondition(string alarmNodeId, AlarmConditionSnapshot state, DateTime sourceTimestampUtc, AddressSpaceRealm realm)
+        => _inner.WriteAlarmCondition(alarmNodeId, state, sourceTimestampUtc, realm);
+
+    public void WriteAlarmQuality(string alarmNodeId, OpcUaQuality quality, DateTime sourceTimestampUtc, AddressSpaceRealm realm)
+        => _inner.WriteAlarmQuality(alarmNodeId, quality, sourceTimestampUtc, realm);

    /// <inheritdoc />
-    public void MaterialiseAlarmCondition(string alarmNodeId, string equipmentNodeId, string displayName, string alarmType, int severity, bool isNative = false)
-        => _inner.MaterialiseAlarmCondition(alarmNodeId, equipmentNodeId, displayName, alarmType, severity, isNative);
+    public void MaterialiseAlarmCondition(string alarmNodeId, string equipmentNodeId, string displayName, string alarmType, int severity, AddressSpaceRealm realm, bool isNative = false)
+        => _inner.MaterialiseAlarmCondition(alarmNodeId, equipmentNodeId, displayName, alarmType, severity, realm, isNative);

    /// <inheritdoc />
-    public void EnsureFolder(string folderNodeId, string? parentNodeId, string displayName)
-        => _inner.EnsureFolder(folderNodeId, parentNodeId, displayName);
+    // Forward the WP4 multi-notifier wiring to the inner sink. Without this the native-alarm fan-out to the
+    // referencing equipment folders ships INERT on every driver-role host (actors inject THIS wrapper, not the
+    // inner SdkAddressSpaceSink) — the F10b / PR#423 forwarding trap the reflection guard exists to catch.
+    public void WireAlarmNotifiers(string alarmNodeId, AddressSpaceRealm alarmRealm, IReadOnlyList<string> notifierFolderNodeIds, AddressSpaceRealm notifierFolderRealm)
+        => _inner.WireAlarmNotifiers(alarmNodeId, alarmRealm, notifierFolderNodeIds, notifierFolderRealm);

    /// <inheritdoc />
-    public void EnsureVariable(string variableNodeId, string? parentFolderNodeId, string displayName, string dataType, bool writable, string? historianTagname = null, bool isArray = false, uint? arrayLength = null)
-        => _inner.EnsureVariable(variableNodeId, parentFolderNodeId, displayName, dataType, writable, historianTagname, isArray, arrayLength);
+    public void EnsureFolder(string folderNodeId, string? parentNodeId, string displayName, AddressSpaceRealm realm)
+        => _inner.EnsureFolder(folderNodeId, parentNodeId, displayName, realm);
+
+    /// <inheritdoc />
+    public void EnsureVariable(string variableNodeId, string? parentFolderNodeId, string displayName, string dataType, bool writable, AddressSpaceRealm realm, string? historianTagname = null, bool isArray = false, uint? arrayLength = null)
+        => _inner.EnsureVariable(variableNodeId, parentFolderNodeId, displayName, dataType, writable, realm, historianTagname, isArray, arrayLength);

    /// <inheritdoc />
    public void RebuildAddressSpace() => _inner.RebuildAddressSpace();

    /// <inheritdoc />
-    public void RaiseNodesAddedModelChange(string affectedNodeId) => _inner.RaiseNodesAddedModelChange(affectedNodeId);
+    public void RaiseNodesAddedModelChange(string affectedNodeId, AddressSpaceRealm realm) => _inner.RaiseNodesAddedModelChange(affectedNodeId, realm);
+
+    /// <inheritdoc />
+    public void AddReference(string sourceNodeId, AddressSpaceRealm sourceRealm, string targetNodeId, AddressSpaceRealm targetRealm, string referenceType = "Organizes")
+        => _inner.AddReference(sourceNodeId, sourceRealm, targetNodeId, targetRealm, referenceType);

    /// <inheritdoc />
    // Forwards to the inner sink when it supports the surgical capability; returns false otherwise —
@@ -55,9 +69,9 @@ public sealed class DeferredAddressSpaceSink : IOpcUaAddressSpaceSink, ISurgical
    // Without this forward the surgical optimization is inert on every driver-role host, because
    // actors inject THIS wrapper, not the inner sink. ALL six args (including the DataType/array-shape
    // ones) MUST be forwarded — a partial forward silently drops the shape update on every driver-role host.
-    public bool UpdateTagAttributes(string variableNodeId, bool writable, string? historianTagname, string dataType, bool isArray, uint? arrayLength)
+    public bool UpdateTagAttributes(string variableNodeId, bool writable, string? historianTagname, string dataType, bool isArray, uint? arrayLength, AddressSpaceRealm realm)
        => _inner is ISurgicalAddressSpaceSink surgical
-           && surgical.UpdateTagAttributes(variableNodeId, writable, historianTagname, dataType, isArray, arrayLength);
+           && surgical.UpdateTagAttributes(variableNodeId, writable, historianTagname, dataType, isArray, arrayLength, realm);

    /// <inheritdoc />
    // Forwards to the inner sink when it supports the surgical capability; returns false otherwise —
@@ -65,9 +79,9 @@ public sealed class DeferredAddressSpaceSink : IOpcUaAddressSpaceSink, ISurgical
    // sink that isn't surgical — so the caller (AddressSpaceApplier) falls back to a full rebuild.
    // Without this forward the rename-refresh optimization is inert on every driver-role host, because
    // actors inject THIS wrapper, not the inner sink.
-    public bool UpdateFolderDisplayName(string folderNodeId, string displayName)
+    public bool UpdateFolderDisplayName(string folderNodeId, string displayName, AddressSpaceRealm realm)
        => _inner is ISurgicalAddressSpaceSink surgical
-           && surgical.UpdateFolderDisplayName(folderNodeId, displayName);
+           && surgical.UpdateFolderDisplayName(folderNodeId, displayName, realm);

    // R2-07 T7 — surgical remove forwards. Same capability-sniffing pattern as UpdateTagAttributes /
    // UpdateFolderDisplayName: forward when the inner sink supports the surgical capability; return false
@@ -75,14 +89,14 @@ public sealed class DeferredAddressSpaceSink : IOpcUaAddressSpaceSink, ISurgical
    // (AddressSpaceApplier) falls back to a full rebuild. Without these forwards the surgical remove path is
    // inert on every driver-role host — the F10b / PR#423 trap the reflection guard exists to catch.
    /// <inheritdoc />
-    public bool RemoveVariableNode(string variableNodeId)
-        => _inner is ISurgicalAddressSpaceSink surgical && surgical.RemoveVariableNode(variableNodeId);
+    public bool RemoveVariableNode(string variableNodeId, AddressSpaceRealm realm)
+        => _inner is ISurgicalAddressSpaceSink surgical && surgical.RemoveVariableNode(variableNodeId, realm);

    /// <inheritdoc />
-    public bool RemoveAlarmConditionNode(string alarmNodeId)
-        => _inner is ISurgicalAddressSpaceSink surgical && surgical.RemoveAlarmConditionNode(alarmNodeId);
+    public bool RemoveAlarmConditionNode(string alarmNodeId, AddressSpaceRealm realm)
+        => _inner is ISurgicalAddressSpaceSink surgical && surgical.RemoveAlarmConditionNode(alarmNodeId, realm);

    /// <inheritdoc />
-    public bool RemoveEquipmentSubtree(string equipmentNodeId)
-        => _inner is ISurgicalAddressSpaceSink surgical && surgical.RemoveEquipmentSubtree(equipmentNodeId);
+    public bool RemoveEquipmentSubtree(string equipmentNodeId, AddressSpaceRealm realm)
+        => _inner is ISurgicalAddressSpaceSink surgical && surgical.RemoveEquipmentSubtree(equipmentNodeId, realm);
 }
@@ -1,31 +0,0 @@
-namespace ZB.MOM.WW.OtOpcUa.Commons.OpcUa;
-
-/// <summary>
-///     Single source of truth for equipment-namespace OPC UA NodeId strings. The variable NodeId is
-///     FOLDER-SCOPED (<c>{parent}/{Name}</c>), NOT the driver-side FullName — a driver wire ref is not
-///     unique across identical machines, so FullName-as-NodeId would collide in the sink. Used by the
-///     materialiser (AddressSpaceApplier), the VirtualTag publish map, and the driver live-value router so all
-///     three agree on the exact NodeId a variable was placed at.
-/// </summary>
-public static class EquipmentNodeIds
-{
-    /// <summary>The sub-folder NodeId under an equipment for a non-empty FolderPath: <c>{equipmentId}/{folderPath}</c>.</summary>
-    /// <param name="equipmentId">The owning equipment's NodeId.</param>
-    /// <param name="folderPath">The tag/vtag FolderPath (must be non-empty for this to be meaningful).</param>
-    /// <returns>The sub-folder NodeId string.</returns>
-    public static string SubFolder(string equipmentId, string folderPath) => $"{equipmentId}/{folderPath}";
-
-    /// <summary>
-    ///     The folder-scoped variable NodeId: <c>{parent}/{name}</c> where <c>parent = equipmentId</c> when
-    ///     <paramref name="folderPath"/> is null/empty, else <see cref="SubFolder"/>.
-    /// </summary>
-    /// <param name="equipmentId">The owning equipment's NodeId.</param>
-    /// <param name="folderPath">The tag/vtag FolderPath, or null/empty for "directly under the equipment".</param>
-    /// <param name="name">The tag/vtag Name (the leaf browse segment).</param>
-    /// <returns>The folder-scoped variable NodeId string.</returns>
-    public static string Variable(string equipmentId, string? folderPath, string name)
-    {
-        var parent = string.IsNullOrWhiteSpace(folderPath) ? equipmentId : SubFolder(equipmentId, folderPath);
-        return $"{parent}/{name}";
-    }
-}
@@ -13,7 +13,11 @@ public interface IOpcUaAddressSpaceSink
    /// <param name="value">The value to write.</param>
    /// <param name="quality">The quality status of the value.</param>
    /// <param name="sourceTimestampUtc">The source timestamp in UTC.</param>
-    void WriteValue(string nodeId, object? value, OpcUaQuality quality, DateTime sourceTimestampUtc);
+    /// <param name="realm">Which of the two v3 namespaces (<see cref="AddressSpaceRealm.Raw"/> device tree or
+    /// <see cref="AddressSpaceRealm.Uns"/> equipment tree) the <paramref name="nodeId"/> lives in — the sink
+    /// resolves the namespace index from the realm rather than parsing it out of the id string. WP3's fan-out
+    /// calls this once per NodeId (raw + every referencing UNS node) with the matching realm.</param>
+    void WriteValue(string nodeId, object? value, OpcUaQuality quality, DateTime sourceTimestampUtc, AddressSpaceRealm realm);

    /// <summary>Write an alarm-condition's full Part 9 state. When a real condition node has been
    /// materialised for <paramref name="alarmNodeId"/> via <see cref="MaterialiseAlarmCondition"/>,
@@ -25,7 +29,20 @@ public interface IOpcUaAddressSpaceSink
    /// <param name="alarmNodeId">The OPC UA node ID of the alarm (== ScriptedAlarmId for materialised conditions).</param>
    /// <param name="state">The full condition state to project onto the node.</param>
    /// <param name="sourceTimestampUtc">The source timestamp in UTC.</param>
-    void WriteAlarmCondition(string alarmNodeId, AlarmConditionSnapshot state, DateTime sourceTimestampUtc);
+    /// <param name="realm">The namespace realm <paramref name="alarmNodeId"/> lives in (must match the realm
+    /// the condition was materialised under).</param>
+    void WriteAlarmCondition(string alarmNodeId, AlarmConditionSnapshot state, DateTime sourceTimestampUtc, AddressSpaceRealm realm);
+
+    /// <summary>#477 — annotate a materialised condition's source-data quality OUT OF BAND from any alarm
+    /// transition (used by the driver-connectivity path: comms lost → <see cref="OpcUaQuality.Bad"/>,
+    /// restored → <see cref="OpcUaQuality.Good"/>). Sets ONLY the condition's Quality — never
+    /// Active/Acked/Severity/Retain (a comms-lost active alarm stays active) — and fires one Part 9 event
+    /// only on a quality-bucket change. A no-op for an unmaterialised / non-condition node.</summary>
+    /// <param name="alarmNodeId">The condition node id (RawPath for a native alarm).</param>
+    /// <param name="quality">The source-data quality to annotate.</param>
+    /// <param name="sourceTimestampUtc">The connectivity transition timestamp in UTC.</param>
+    /// <param name="realm">The namespace realm the condition was materialised under.</param>
+    void WriteAlarmQuality(string alarmNodeId, OpcUaQuality quality, DateTime sourceTimestampUtc, AddressSpaceRealm realm);

    /// <summary>
    ///     Materialise a real OPC UA Part 9 alarm-condition node under its equipment folder so clients
@@ -41,7 +58,31 @@ public interface IOpcUaAddressSpaceSink
    /// <param name="isNative">When true this is a driver-fed (native, e.g. Galaxy) equipment-tag alarm; when
    /// false (default) it is a scripted alarm. The node manager tracks native condition node ids so a later
    /// task can route a native condition's inbound Acknowledge to the driver instead of the scripted engine.</param>
-    void MaterialiseAlarmCondition(string alarmNodeId, string equipmentNodeId, string displayName, string alarmType, int severity, bool isNative = false);
+    /// <param name="realm">The namespace realm the condition (and its parent folder <paramref name="equipmentNodeId"/>)
+    /// live in.</param>
+    void MaterialiseAlarmCondition(string alarmNodeId, string equipmentNodeId, string displayName, string alarmType, int severity, AddressSpaceRealm realm, bool isNative = false);
+
+    /// <summary>
+    ///     v3 Batch 4 (multi-notifier native alarms) — wire an already-materialised native alarm condition
+    ///     (<paramref name="alarmNodeId"/>, materialised at the raw tag via <see cref="MaterialiseAlarmCondition"/>
+    ///     with ConditionId = the RawPath) as an event notifier of EACH referencing equipment's UNS folder, so
+    ///     the condition's <b>single</b> <c>ReportEvent</c> fans one event to every referencing equipment root
+    ///     WITHOUT re-reporting per root (distinct EventIds would break Server-object dedup + Part 9 ack
+    ///     correlation). Per folder the sink wires the SDK's bidirectional notifier pattern
+    ///     (<c>alarm.AddNotifier(isInverse:true, folder)</c> + <c>folder.AddNotifier(isInverse:false, alarm)</c>)
+    ///     and promotes the folder to an event notifier. <b>Idempotent</b> (a re-wire of the same pair updates,
+    ///     never duplicates); a <b>missing endpoint is a no-op</b> (logged, never thrown) so a mid-rebuild race
+    ///     can't fault a deploy. The sink tracks each wired pair so a later rebuild / condition-removal /
+    ///     equipment-subtree-removal tears the notifier down bidirectionally (no inverse-notifier entry leaks
+    ///     across redeploys).
+    /// </summary>
+    /// <param name="alarmNodeId">The native alarm condition's node id (== the backing tag's RawPath).</param>
+    /// <param name="alarmRealm">The namespace realm the condition lives in (Raw for native alarms).</param>
+    /// <param name="notifierFolderNodeIds">The equipment folder node ids (their <c>s=</c> ids) to wire as
+    /// extra event-notifier roots for this condition. An unknown / not-yet-materialised folder id is skipped.</param>
+    /// <param name="notifierFolderRealm">The namespace realm the notifier folders live in (Uns for equipment folders).</param>
+    void WireAlarmNotifiers(string alarmNodeId, AddressSpaceRealm alarmRealm,
+                            IReadOnlyList<string> notifierFolderNodeIds, AddressSpaceRealm notifierFolderRealm);

    /// <summary>
    ///     Ensure a folder node exists under the given parent. Used by <c>AddressSpaceApplier</c> to
@@ -52,7 +93,8 @@ public interface IOpcUaAddressSpaceSink
    /// <param name="folderNodeId">The OPC UA node ID for the folder.</param>
    /// <param name="parentNodeId">The parent folder node ID, or null for namespace root.</param>
    /// <param name="displayName">The display name for the folder.</param>
-    void EnsureFolder(string folderNodeId, string? parentNodeId, string displayName);
+    /// <param name="realm">The namespace realm the folder (and its <paramref name="parentNodeId"/>) live in.</param>
+    void EnsureFolder(string folderNodeId, string? parentNodeId, string displayName, AddressSpaceRealm realm);

    /// <summary>
    ///     Ensure a Variable node exists at <paramref name="variableNodeId"/>, parented under
@@ -77,7 +119,10 @@ public interface IOpcUaAddressSpaceSink
    /// rank + dimensions carry the array-ness.</param>
    /// <param name="arrayLength">The declared length of the 1-D array when <paramref name="isArray"/> is
    /// true; ignored for scalars. Null ⇒ length 0 (unbounded).</param>
-    void EnsureVariable(string variableNodeId, string? parentFolderNodeId, string displayName, string dataType, bool writable, string? historianTagname = null, bool isArray = false, uint? arrayLength = null);
+    /// <param name="realm">The namespace realm the variable (and its <paramref name="parentFolderNodeId"/>) live
+    /// in. A historized UNS reference node registers the SAME <paramref name="historianTagname"/> as its backing
+    /// raw node — both NodeIds map to one tagname — so this call carries the shared tagname per realm.</param>
+    void EnsureVariable(string variableNodeId, string? parentFolderNodeId, string displayName, string dataType, bool writable, AddressSpaceRealm realm, string? historianTagname = null, bool isArray = false, uint? arrayLength = null);

    /// <summary>
    ///     Tear down + repopulate the address space. Called by <c>OpcUaPublishActor</c> after a
@@ -91,7 +136,28 @@ public interface IOpcUaAddressSpaceSink
    ///     (Part 3 GeneralModelChangeEvent, verb NodeAdded).
    /// </summary>
    /// <param name="affectedNodeId">The node under which discovered nodes were added.</param>
-    void RaiseNodesAddedModelChange(string affectedNodeId);
+    /// <param name="realm">The namespace realm <paramref name="affectedNodeId"/> lives in.</param>
+    void RaiseNodesAddedModelChange(string affectedNodeId, AddressSpaceRealm realm);
+
+    /// <summary>
+    ///     Add an OPC UA reference from an already-materialised source node to an already-materialised
+    ///     target node, both realm-qualified. Used by <c>AddressSpaceApplier</c> to link each UNS reference
+    ///     Variable (source, <see cref="AddressSpaceRealm.Uns"/>) to its backing Raw node (target,
+    ///     <see cref="AddressSpaceRealm.Raw"/>) with an <c>Organizes</c> edge, so the UNS variable
+    ///     browse-resolves to its raw source (and the raw node back via the inverse). The edge is wired
+    ///     bidirectionally (forward on the source, inverse on the target) so browse resolves both ways.
+    ///     <b>Idempotent</b> (an existing edge is not duplicated); a <b>missing endpoint is a no-op</b>
+    ///     (logged, never thrown) so a mid-rebuild race can't fault a deploy.
+    /// </summary>
+    /// <param name="sourceNodeId">The source node's <c>s=</c> id (the referencing node — e.g. the UNS variable).</param>
+    /// <param name="sourceRealm">The namespace realm <paramref name="sourceNodeId"/> lives in.</param>
+    /// <param name="targetNodeId">The target node's <c>s=</c> id (the referenced node — e.g. the backing Raw node).</param>
+    /// <param name="targetRealm">The namespace realm <paramref name="targetNodeId"/> lives in.</param>
+    /// <param name="referenceType">The hierarchical reference type name — <c>Organizes</c> (default),
+    /// <c>HasComponent</c>, or <c>HasProperty</c>; unknown names fall back to <c>Organizes</c>.</param>
+    void AddReference(string sourceNodeId, AddressSpaceRealm sourceRealm,
+                      string targetNodeId, AddressSpaceRealm targetRealm,
+                      string referenceType = "Organizes");
 }

 /// <summary>OPC UA status code projection — Good / Uncertain / Bad. Real SDK has finer-grained
@@ -106,23 +172,30 @@ public sealed class NullOpcUaAddressSpaceSink : IOpcUaAddressSpaceSink
    private NullOpcUaAddressSpaceSink() { }

    /// <inheritdoc />
-    public void WriteValue(string nodeId, object? value, OpcUaQuality quality, DateTime sourceTimestampUtc) { }
+    public void WriteValue(string nodeId, object? value, OpcUaQuality quality, DateTime sourceTimestampUtc, AddressSpaceRealm realm) { }

    /// <inheritdoc />
-    public void WriteAlarmCondition(string alarmNodeId, AlarmConditionSnapshot state, DateTime sourceTimestampUtc) { }
+    public void WriteAlarmCondition(string alarmNodeId, AlarmConditionSnapshot state, DateTime sourceTimestampUtc, AddressSpaceRealm realm) { }
+    public void WriteAlarmQuality(string alarmNodeId, OpcUaQuality quality, DateTime sourceTimestampUtc, AddressSpaceRealm realm) { }

    /// <inheritdoc />
-    public void MaterialiseAlarmCondition(string alarmNodeId, string equipmentNodeId, string displayName, string alarmType, int severity, bool isNative = false) { }
+    public void MaterialiseAlarmCondition(string alarmNodeId, string equipmentNodeId, string displayName, string alarmType, int severity, AddressSpaceRealm realm, bool isNative = false) { }

    /// <inheritdoc />
-    public void EnsureFolder(string folderNodeId, string? parentNodeId, string displayName) { }
+    public void WireAlarmNotifiers(string alarmNodeId, AddressSpaceRealm alarmRealm, IReadOnlyList<string> notifierFolderNodeIds, AddressSpaceRealm notifierFolderRealm) { }

    /// <inheritdoc />
-    public void EnsureVariable(string variableNodeId, string? parentFolderNodeId, string displayName, string dataType, bool writable, string? historianTagname = null, bool isArray = false, uint? arrayLength = null) { }
+    public void EnsureFolder(string folderNodeId, string? parentNodeId, string displayName, AddressSpaceRealm realm) { }
+
+    /// <inheritdoc />
+    public void EnsureVariable(string variableNodeId, string? parentFolderNodeId, string displayName, string dataType, bool writable, AddressSpaceRealm realm, string? historianTagname = null, bool isArray = false, uint? arrayLength = null) { }

    /// <inheritdoc />
    public void RebuildAddressSpace() { }

    /// <inheritdoc />
-    public void RaiseNodesAddedModelChange(string affectedNodeId) { }
+    public void RaiseNodesAddedModelChange(string affectedNodeId, AddressSpaceRealm realm) { }
+
+    /// <inheritdoc />
+    public void AddReference(string sourceNodeId, AddressSpaceRealm sourceRealm, string targetNodeId, AddressSpaceRealm targetRealm, string referenceType = "Organizes") { }
 }
@@ -11,11 +11,17 @@ public interface IOpcUaNodeWriteGateway
 {
    /// <summary>Route a write of <paramref name="value"/> to the driver backing node
    /// <paramref name="nodeId"/>; the returned task resolves with the device-write outcome.</summary>
-    /// <param name="nodeId">The folder-scoped equipment-variable node id being written.</param>
+    /// <param name="nodeId">The full ns-qualified node id being written (<c>node.NodeId.ToString()</c>).</param>
    /// <param name="value">The value the client wrote.</param>
+    /// <param name="realm">Which of the two v3 namespaces (<see cref="AddressSpaceRealm.Raw"/> device tree or
+    /// <see cref="AddressSpaceRealm.Uns"/> equipment tree) <paramref name="nodeId"/> lives in — the node
+    /// manager resolves it from the node's namespace index (<c>RealmOf</c>). It is REQUIRED for correct
+    /// routing: a raw <c>s=&lt;RawPath&gt;</c> and a UNS <c>s=&lt;Area/Line/Equip/Eff&gt;</c> can collide as bare
+    /// strings, so the routing map is keyed by <c>(realm, bareId)</c> — dropping the realm would let an
+    /// operator write route to the WRONG driver ref.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>A task resolving to the device-write outcome.</returns>
-    Task<NodeWriteOutcome> WriteAsync(string nodeId, object? value, CancellationToken ct);
+    Task<NodeWriteOutcome> WriteAsync(string nodeId, object? value, AddressSpaceRealm realm, CancellationToken ct);
 }

 /// <summary>Outcome of routing an inbound node write to the backing driver.</summary>
@@ -31,6 +37,6 @@ public sealed class NullOpcUaNodeWriteGateway : IOpcUaNodeWriteGateway
    public static readonly NullOpcUaNodeWriteGateway Instance = new();
    private NullOpcUaNodeWriteGateway() { }
    /// <inheritdoc />
-    public Task<NodeWriteOutcome> WriteAsync(string nodeId, object? value, CancellationToken ct) =>
+    public Task<NodeWriteOutcome> WriteAsync(string nodeId, object? value, AddressSpaceRealm realm, CancellationToken ct) =>
        Task.FromResult(new NodeWriteOutcome(false, "writes unavailable"));
 }
@@ -21,8 +21,10 @@ public interface ISurgicalAddressSpaceSink
    /// <param name="dataType">The OPC UA built-in data type name (e.g. "Boolean", "Int32", "Float").</param>
    /// <param name="isArray">When true the node is a 1-D array (ValueRank=OneDimension); when false scalar.</param>
    /// <param name="arrayLength">The declared length of the 1-D array when <paramref name="isArray"/> is true; ignored for scalars.</param>
+    /// <param name="realm">The namespace realm <paramref name="variableNodeId"/> lives in — the sink resolves the
+    /// namespace index from the realm rather than parsing it out of the id string.</param>
    /// <returns>True when the in-place update was applied; false when the node is missing (caller rebuilds).</returns>
-    bool UpdateTagAttributes(string variableNodeId, bool writable, string? historianTagname, string dataType, bool isArray, uint? arrayLength);
+    bool UpdateTagAttributes(string variableNodeId, bool writable, string? historianTagname, string dataType, bool isArray, uint? arrayLength, AddressSpaceRealm realm);

    /// <summary>Update an existing folder node's <c>DisplayName</c> IN PLACE, notifying subscribers
    /// (ClearChangeMasks) without a rebuild — used by AddressSpaceApplier to apply a UNS Area / Line
@@ -32,8 +34,9 @@ public interface ISurgicalAddressSpaceSink
    /// should rebuild instead).</summary>
    /// <param name="folderNodeId">The node id of the folder whose display name to update in place.</param>
    /// <param name="displayName">The new display name to apply.</param>
+    /// <param name="realm">The namespace realm <paramref name="folderNodeId"/> lives in.</param>
    /// <returns>True when the in-place update was applied; false when the folder is missing (caller rebuilds).</returns>
-    bool UpdateFolderDisplayName(string folderNodeId, string displayName);
+    bool UpdateFolderDisplayName(string folderNodeId, string displayName, AddressSpaceRealm realm);

    /// <summary>Remove ONE existing value-variable node IN PLACE (detach from its parent, drop it from the
    /// predefined-node set, drop any historized-tagname registration), then raise a Part 3
@@ -43,8 +46,9 @@ public interface ISurgicalAddressSpaceSink
    /// re-subscription attempts get BadNodeIdUnknown from the SDK. Returns false when the node id is unknown
    /// (the node-manager maps drifted from the plan — caller falls back to a full rebuild).</summary>
    /// <param name="variableNodeId">The folder-scoped node id of the variable to remove in place.</param>
+    /// <param name="realm">The namespace realm <paramref name="variableNodeId"/> lives in.</param>
    /// <returns>True when the node was removed; false when the id is unknown (caller rebuilds).</returns>
-    bool RemoveVariableNode(string variableNodeId);
+    bool RemoveVariableNode(string variableNodeId, AddressSpaceRealm realm);

    /// <summary>Remove ONE existing Part 9 alarm-condition node IN PLACE (detach, drop from the
    /// predefined-node set, clear the native-alarm flag), then raise NodeDeleted outside the lock. The
@@ -52,8 +56,9 @@ public interface ISurgicalAddressSpaceSink
    /// stops replaying on ConditionRefresh. Returns false when the condition id is unknown (caller
    /// rebuilds).</summary>
    /// <param name="alarmNodeId">The alarm condition node id (== ScriptedAlarmId, or a native alarm tag's folder-scoped id).</param>
+    /// <param name="realm">The namespace realm <paramref name="alarmNodeId"/> lives in.</param>
    /// <returns>True when the condition was removed; false when the id is unknown (caller rebuilds).</returns>
-    bool RemoveAlarmConditionNode(string alarmNodeId);
+    bool RemoveAlarmConditionNode(string alarmNodeId, AddressSpaceRealm realm);

    /// <summary>Remove an equipment folder AND its entire descendant subtree (sub-folders, value variables,
    /// condition nodes) IN PLACE: per-descendant map/registration cleanup (variables, historized tagnames,
@@ -62,6 +67,7 @@ public interface ISurgicalAddressSpaceSink
    /// the equipment folder outside the lock. Returns false when the folder id is unknown (caller
    /// rebuilds).</summary>
    /// <param name="equipmentNodeId">The equipment folder node id whose entire subtree to remove.</param>
+    /// <param name="realm">The namespace realm <paramref name="equipmentNodeId"/> lives in.</param>
    /// <returns>True when the subtree was removed; false when the id is unknown (caller rebuilds).</returns>
-    bool RemoveEquipmentSubtree(string equipmentNodeId);
+    bool RemoveEquipmentSubtree(string equipmentNodeId, AddressSpaceRealm realm);
 }
@@ -0,0 +1,110 @@
+using ZB.MOM.WW.OtOpcUa.Commons.Types;
+
+namespace ZB.MOM.WW.OtOpcUa.Commons.OpcUa;
+
+/// <summary>
+///     v3 dual-namespace NodeId + namespace-URI authority. Two OPC UA namespaces expose the same
+///     underlying values under two identity schemes:
+///     <list type="bullet">
+///       <item><b>Raw</b> (<see cref="RawNamespaceUri"/>): the device-oriented tree
+///         Folder→Driver→Device→TagGroup→Tag. A node's <c>s=</c> identifier IS its
+///         <see cref="RawPaths">RawPath</see> — folders/drivers/devices/groups included (each keys
+///         on its own RawPath prefix).</item>
+///       <item><b>Uns</b> (<see cref="UnsNamespaceUri"/>): the equipment-oriented tree
+///         Area→Line→Equipment→signal. A node's <c>s=</c> identifier is the slash-joined
+///         <c>Area/Line/Equipment[/EffectiveName]</c>.</item>
+///     </list>
+///     These replace the single <c>https://zb.com/otopcua/ns</c> namespace and the retired
+///     <c>EquipmentNodeIds</c> ({equipmentId}/{folderPath}/{name}) scheme. Realm travels alongside
+///     the identifier as an <see cref="AddressSpaceRealm"/> at every sink seam — the namespace is
+///     never parsed back out of the id string. Both schemes share <see cref="RawPaths.Separator"/>
+///     and its ordinal, case-sensitive segment charset so identity is enforced in one place.
+/// </summary>
+public static class V3NodeIds
+{
+    /// <summary>The Raw namespace URI (device-oriented subtree).</summary>
+    public const string RawNamespaceUri = "https://zb.com/otopcua/raw";
+
+    /// <summary>The UNS namespace URI (equipment-oriented subtree).</summary>
+    public const string UnsNamespaceUri = "https://zb.com/otopcua/uns";
+
+    /// <summary>The namespace URI for a realm.</summary>
+    /// <param name="realm">The address-space realm.</param>
+    /// <returns>The realm's namespace URI.</returns>
+    /// <exception cref="ArgumentOutOfRangeException">Unknown realm.</exception>
+    public static string NamespaceUri(AddressSpaceRealm realm) => realm switch
+    {
+        AddressSpaceRealm.Raw => RawNamespaceUri,
+        AddressSpaceRealm.Uns => UnsNamespaceUri,
+        _ => throw new ArgumentOutOfRangeException(nameof(realm), realm, "Unknown address-space realm."),
+    };
+
+    // ----- Raw realm -----
+
+    /// <summary>
+    ///     The Raw-namespace <c>s=</c> identifier for a raw node — identical to its
+    ///     <see cref="RawPaths">RawPath</see> (folders, drivers, devices, groups, and tags all key
+    ///     on their own RawPath). A pass-through seam so call sites read intent rather than a bare
+    ///     string; the argument is expected to already be a RawPaths-built path.
+    /// </summary>
+    /// <param name="rawPath">The (already-built) RawPath.</param>
+    /// <returns>The Raw-namespace <c>s=</c> identifier (== <paramref name="rawPath"/>).</returns>
+    public static string Raw(string rawPath)
+    {
+        ArgumentException.ThrowIfNullOrEmpty(rawPath);
+        return rawPath;
+    }
+
+    // ----- Uns realm -----
+
+    /// <summary>
+    ///     The UNS-namespace <c>s=</c> identifier for a folder or variable, slash-joined from
+    ///     ordered segments (Area, then Line, then Equipment, then an optional EffectiveName).
+    ///     Every segment is validated via <see cref="RawPaths.ValidateSegment"/> (no embedded
+    ///     separator, no leading/trailing whitespace) so a UNS id round-trips like a RawPath.
+    /// </summary>
+    /// <param name="segments">The ordered, non-empty segments (Area → leaf).</param>
+    /// <returns>The slash-joined UNS <c>s=</c> identifier.</returns>
+    /// <exception cref="ArgumentException">A segment is invalid, or the sequence is empty.</exception>
+    public static string Uns(params string[] segments) => UnsFromSegments(segments);
+
+    /// <summary>Build a UNS <c>s=</c> identifier from ordered segments. See <see cref="Uns(string[])"/>.</summary>
+    /// <param name="segments">The ordered, non-empty segments (Area → leaf).</param>
+    /// <returns>The slash-joined UNS <c>s=</c> identifier.</returns>
+    public static string Uns(IEnumerable<string> segments) => UnsFromSegments(segments);
+
+    /// <summary>
+    ///     Append a child segment (a Line under an Area, an Equipment under a Line, an
+    ///     EffectiveName under an Equipment) to an already-built UNS path.
+    /// </summary>
+    /// <param name="parentUnsPath">The parent UNS path (assumed already valid).</param>
+    /// <param name="childSegment">The child segment to append.</param>
+    /// <returns>The combined UNS <c>s=</c> identifier.</returns>
+    /// <exception cref="ArgumentException">The child segment is invalid, or the parent is blank.</exception>
+    public static string UnsChild(string parentUnsPath, string childSegment)
+    {
+        ArgumentException.ThrowIfNullOrEmpty(parentUnsPath);
+        var error = RawPaths.ValidateSegment(childSegment);
+        if (error is not null)
+            throw new ArgumentException($"Invalid UNS NodeId segment ('{childSegment}'): {error}", nameof(childSegment));
+
+        return parentUnsPath + RawPaths.Separator + childSegment;
+    }
+
+    private static string UnsFromSegments(IEnumerable<string> segments)
+    {
+        ArgumentNullException.ThrowIfNull(segments);
+        var list = segments as IReadOnlyList<string> ?? segments.ToList();
+        if (list.Count == 0)
+            throw new ArgumentException("A UNS NodeId must have at least one segment.", nameof(segments));
+
+        for (var i = 0; i < list.Count; i++)
+        {
+            var error = RawPaths.ValidateSegment(list[i]);
+            if (error is not null)
+                throw new ArgumentException($"Invalid UNS NodeId segment at index {i} ('{list[i]}'): {error}", nameof(segments));
+        }
+
+        return string.Join(RawPaths.Separator, list);
+    }
+}
@@ -0,0 +1,94 @@
+namespace ZB.MOM.WW.OtOpcUa.Commons.Types;
+
+/// <summary>
+///     Builds the per-equipment reference map — <c>equipmentId → (effectiveName → backing-tag RawPath)</c> —
+///     the single authority both compose seams (<c>AddressSpaceComposer</c> + <c>DeploymentArtifact</c>)
+///     and the draft validator use to resolve <c>{{equip}}/&lt;RefName&gt;</c> script paths. A reference's
+///     <b>effective name</b> is its <c>DisplayNameOverride</c> else the backing raw tag's <c>Name</c>; the
+///     RawPath is computed through the shared <see cref="RawPathResolver"/> (the same identity authority the
+///     rest of v3 uses), so the entity side (authoring/validation) and the artifact-decode side agree
+///     byte-for-byte.
+///     <para>Input-shape agnostic + pure: callers flatten their references (EF entities on one side,
+///     artifact JSON on the other) into the same primitive tuple + tag lookup, so the join, the
+///     effective-name rule, and the collision policy live ONLY here. References are consumed in
+///     <c>UnsTagReferenceId</c>-ordinal order and effective-name collisions keep the FIRST — a valid draft
+///     has none (the uniqueness validator rejects them), and the deterministic first-wins keeps the two
+///     seams parity-stable on any input.</para>
+/// </summary>
+public static class EquipmentReferenceMap
+{
+    /// <summary>A flattened UNS tag reference: which equipment references which raw tag under an optional override.</summary>
+    /// <param name="UnsTagReferenceId">Stable logical id — the ordering key for deterministic first-wins.</param>
+    /// <param name="EquipmentId">The referencing equipment.</param>
+    /// <param name="TagId">The backing raw tag.</param>
+    /// <param name="DisplayNameOverride">Optional effective-name override; <see langword="null"/> = use the raw tag's Name.</param>
+    public readonly record struct ReferenceRow(string UnsTagReferenceId, string EquipmentId, string TagId, string? DisplayNameOverride);
+
+    /// <summary>The backing raw tag's identity inputs for its RawPath + effective name.</summary>
+    /// <param name="Name">The raw tag's leaf name (also the default effective name).</param>
+    /// <param name="DeviceId">The tag's owning device id.</param>
+    /// <param name="TagGroupId">The tag's owning tag-group id, or <see langword="null"/> when directly under the device.</param>
+    public readonly record struct TagRow(string Name, string DeviceId, string? TagGroupId);
+
+    /// <summary>
+    ///     Build the reference map. For each reference (ordered by <c>UnsTagReferenceId</c>), resolve the
+    ///     backing tag's RawPath via <paramref name="resolver"/> and key it under the effective name within
+    ///     the owning equipment. References whose backing tag is unknown or whose RawPath cannot be built
+    ///     (broken chain) are skipped. Effective-name collisions within an equipment keep the first.
+    /// </summary>
+    /// <param name="references">The flattened UNS tag references (any order; sorted internally).</param>
+    /// <param name="tagsById">Backing raw tags keyed by <c>TagId</c>.</param>
+    /// <param name="resolver">The shared RawPath resolver over the raw topology.</param>
+    /// <returns><c>equipmentId → (effectiveName → RawPath)</c>. Equipments with no resolvable reference are absent.</returns>
+    public static IReadOnlyDictionary<string, IReadOnlyDictionary<string, string>> Build(
+        IEnumerable<ReferenceRow> references,
+        IReadOnlyDictionary<string, TagRow> tagsById,
+        RawPathResolver resolver)
+    {
+        ArgumentNullException.ThrowIfNull(references);
+        ArgumentNullException.ThrowIfNull(tagsById);
+        ArgumentNullException.ThrowIfNull(resolver);
+
+        var byEquip = new Dictionary<string, Dictionary<string, string>>(StringComparer.Ordinal);
+
+        foreach (var r in references.OrderBy(x => x.UnsTagReferenceId, StringComparer.Ordinal))
+        {
+            if (string.IsNullOrEmpty(r.EquipmentId) || string.IsNullOrEmpty(r.TagId)) continue;
+            if (!tagsById.TryGetValue(r.TagId, out var tag)) continue;
+            var effectiveName = string.IsNullOrEmpty(r.DisplayNameOverride) ? tag.Name : r.DisplayNameOverride!;
+            if (string.IsNullOrEmpty(effectiveName)) continue;
+            var rawPath = resolver.TryBuildTagPath(tag.DeviceId, tag.TagGroupId, tag.Name);
+            if (rawPath is null) continue; // broken chain — dropped (deploy gate rejects invalid names)
+
+            if (!byEquip.TryGetValue(r.EquipmentId, out var map))
+                byEquip[r.EquipmentId] = map = new Dictionary<string, string>(StringComparer.Ordinal);
+            map.TryAdd(effectiveName, rawPath); // first-wins on collision (validator rejects real collisions)
+        }
+
+        return byEquip.ToDictionary(
+            kv => kv.Key,
+            kv => (IReadOnlyDictionary<string, string>)kv.Value,
+            StringComparer.Ordinal);
+    }
+
+    /// <summary>The set of effective names a single equipment's references contribute (for the authoring
+    /// gate + Monaco completion, which need only the names — not the RawPaths).</summary>
+    /// <param name="references">The flattened UNS tag references for (typically) one equipment.</param>
+    /// <param name="tagNameById">Backing raw tag Name keyed by <c>TagId</c>.</param>
+    /// <returns>The distinct effective names, ordinal.</returns>
+    public static IReadOnlySet<string> EffectiveNames(
+        IEnumerable<ReferenceRow> references,
+        IReadOnlyDictionary<string, string> tagNameById)
+    {
+        ArgumentNullException.ThrowIfNull(references);
+        ArgumentNullException.ThrowIfNull(tagNameById);
+        var names = new HashSet<string>(StringComparer.Ordinal);
+        foreach (var r in references)
+        {
+            var effectiveName = r.DisplayNameOverride
+                ?? (tagNameById.TryGetValue(r.TagId, out var n) ? n : null);
+            if (!string.IsNullOrEmpty(effectiveName)) names.Add(effectiveName);
+        }
+        return names;
+    }
+}
@@ -3,19 +3,29 @@ using System.Text.RegularExpressions;
 namespace ZB.MOM.WW.OtOpcUa.Commons.Types;

 /// <summary>
-/// Helpers for equipment-relative virtual-tag script paths. The reserved token
-/// <c>{{equip}}</c> inside a <c>ctx.GetTag</c>/<c>ctx.SetVirtualTag</c> path literal is
-/// replaced at the compose seams with the owning equipment's tag base prefix (derived
-/// from its child-tag <c>FullName</c>s). Pure + regex-based (no Roslyn) so the OpcUaServer
-/// composer and the Runtime artifact-decode path can both share it. Also the single home
-/// for the <c>ctx.GetTag("…")</c> dependency-ref extraction those two seams used to
-/// duplicate.
+/// Helpers for equipment-relative virtual-tag / scripted-alarm script paths. The reserved token
+/// <c>{{equip}}/&lt;RefName&gt;</c> inside a <c>ctx.GetTag</c>/<c>ctx.SetVirtualTag</c> path literal is
+/// replaced at the compose seams (<c>AddressSpaceComposer</c> + <c>DeploymentArtifact</c>) with the
+/// backing raw tag's <c>RawPath</c>, resolved through the owning equipment's
+/// <c>UnsTagReference</c> rows by effective name (<c>&lt;RefName&gt;</c>).
+/// <para><b>v3 syntax:</b> the token joint is a <b>slash</b> — <c>{{equip}}/&lt;RefName&gt;</c> — replacing
+/// the v2 dot-prefix derivation (<c>{{equip}}.X</c>). <c>&lt;RefName&gt;</c> is a reference's effective name
+/// (its <c>DisplayNameOverride</c> else the backing raw tag's <c>Name</c>). An unresolved
+/// <c>&lt;RefName&gt;</c> is left un-substituted (substitution never throws); the deploy-time validator +
+/// the authoring gate + the Monaco diagnostic reject it first, preserving the invariant
+/// <b>the editor accepts ⇔ publish accepts</b>.</para>
+/// Pure + regex-based (no Roslyn) so the OpcUaServer composer and the Runtime artifact-decode path can
+/// both share it. Also the single home for the <c>ctx.GetTag("…")</c> dependency-ref extraction those
+/// two seams used to duplicate.
 /// </summary>
 public static class EquipmentScriptPaths
 {
-    /// <summary>The reserved equipment-base token.</summary>
+    /// <summary>The reserved equipment token stem.</summary>
    public const string EquipToken = "{{equip}}";

+    /// <summary>The reserved equipment reference-relative prefix — the token stem plus the slash joint.</summary>
+    public const string EquipTokenPrefix = "{{equip}}/";
+
    // ctx.GetTag("ref") — reads only; the dependency graph subscribes to exactly these.
    private static readonly Regex GetTagRefRegex =
        new(@"ctx\s*\.\s*GetTag\s*\(\s*""([^""]+)""\s*\)", RegexOptions.Compiled);
@@ -32,6 +42,14 @@ public static class EquipmentScriptPaths
    private static readonly Regex PathLiteralRegex =
        new(@"(ctx\s*\.\s*(?:GetTag|SetVirtualTag)\s*\(\s*"")([^""]*)("")", RegexOptions.Compiled);

+    // {{equip}}/<RefName> occurrence in FREE TEXT (message templates). <RefName> runs until the next
+    // delimiter that cannot appear in an intra-literal RawPath segment used inline in a template —
+    // whitespace, quote, brace, paren, semicolon, or the '/' separator. (Reference effective names may
+    // contain internal spaces; that space-bearing form is unambiguous only inside a path literal, so the
+    // free-text scan is best-effort — see ExtractEquipReferenceNamesFromText.)
+    private static readonly Regex EquipRefTextRegex =
+        new(@"\{\{equip\}\}/([^\s""{}();/]+)", RegexOptions.Compiled);
+
    // A pure pass-through virtual-tag body: exactly `return ctx.GetTag("<ref>").Value;`
    // (whitespace-insensitive). Captures <ref> for relay→alias conversion. Anything with extra
    // statements, arithmetic, a different member than .Value, or multiple GetTag calls is NOT a relay.
@@ -46,44 +64,89 @@ public static class EquipmentScriptPaths
        !string.IsNullOrEmpty(source) && source.Contains(EquipToken, StringComparison.Ordinal);

    /// <summary>
-    /// Equipment tag base = the single shared substring-before-first-dot across the
-    /// equipment's child-tag <c>FullName</c>s. Returns <c>null</c> when there are no usable
-    /// FullNames or they don't agree on one prefix (equipment spanning multiple objects).
+    /// Replace each <c>{{equip}}/&lt;RefName&gt;</c> reference-relative path with the backing raw tag's
+    /// <c>RawPath</c> from <paramref name="referenceMap"/> (effective name → RawPath), inside
+    /// <c>ctx.GetTag</c>/<c>ctx.SetVirtualTag</c> path literals only. A path literal whose content is
+    /// <c>{{equip}}/&lt;RefName&gt;</c> is treated as a single reference: <c>&lt;RefName&gt;</c> is the
+    /// entire remainder after the prefix (so reference effective names may contain internal spaces).
+    /// Identity when <paramref name="source"/> is null/empty, <paramref name="referenceMap"/> is empty,
+    /// or the token is absent (so every existing script — none of which use the token — is byte-unchanged).
+    /// An <c>&lt;RefName&gt;</c> absent from the map is left un-substituted (never throws) — the validator
+    /// rejects it first at deploy.
    /// </summary>
-    /// <param name="childFullNames">The equipment's child-tag driver FullNames.</param>
-    /// <returns>The shared base prefix, or null when none/ambiguous.</returns>
-    public static string? DeriveEquipmentBase(IEnumerable<string?> childFullNames)
+    /// <param name="source">The script source.</param>
+    /// <param name="referenceMap">The equipment's reference map: effective name → backing-tag RawPath.</param>
+    /// <returns>The source with each resolvable <c>{{equip}}/&lt;RefName&gt;</c> substituted inside path literals.</returns>
+    public static string SubstituteEquipmentToken(string source, IReadOnlyDictionary<string, string> referenceMap)
    {
-        string? found = null;
-        foreach (var fn in childFullNames)
-        {
-            if (string.IsNullOrWhiteSpace(fn)) continue;
-            var dot = fn.IndexOf('.');
-            var prefix = dot < 0 ? fn : fn.Substring(0, dot);
-            if (prefix.Length == 0) continue;
-            if (found is null) found = prefix;
-            else if (!string.Equals(found, prefix, StringComparison.Ordinal)) return null;
-        }
-        return found;
+        if (string.IsNullOrEmpty(source) || referenceMap is null || referenceMap.Count == 0) return source;
+        if (!source.Contains(EquipTokenPrefix, StringComparison.Ordinal)) return source;
+        return PathLiteralRegex.Replace(source, m =>
+            m.Groups[1].Value
+            + SubstituteContent(m.Groups[2].Value, referenceMap)
+            + m.Groups[3].Value);
+    }
+
+    // Substitute the reference-relative token inside a single path-literal's content. The content is one
+    // whole tag path; when it starts with the {{equip}}/ prefix the remainder is the reference name.
+    private static string SubstituteContent(string content, IReadOnlyDictionary<string, string> referenceMap)
+    {
+        if (!content.StartsWith(EquipTokenPrefix, StringComparison.Ordinal)) return content;
+        var refName = content.Substring(EquipTokenPrefix.Length);
+        if (refName.Length == 0) return content;
+        return referenceMap.TryGetValue(refName, out var rawPath) ? rawPath : content;
    }

    /// <summary>
-    /// Replace <c>{{equip}}</c> with <paramref name="equipBase"/> inside
-    /// <c>ctx.GetTag</c>/<c>ctx.SetVirtualTag</c> path literals only. Identity when
-    /// <paramref name="equipBase"/> is null/empty or the token is absent (so every existing
-    /// script — none of which use the token — is byte-unchanged).
+    /// Distinct <c>&lt;RefName&gt;</c> values used via <c>{{equip}}/&lt;RefName&gt;</c> inside
+    /// <c>ctx.GetTag</c>/<c>ctx.SetVirtualTag</c> path literals, in first-seen order. Scoped to the SAME
+    /// path literals <see cref="SubstituteEquipmentToken"/> operates on (so a token in a comment / logger
+    /// string is not reported), and the entire post-prefix remainder is the reference name (matching
+    /// substitution) — this keeps the validator / authoring gate / Monaco diagnostic in lockstep with what
+    /// resolves. Feeds the deploy-gate + authoring rejection + editor completion.
    /// </summary>
-    /// <param name="source">The script source.</param>
-    /// <param name="equipBase">The equipment base prefix, or null/empty for no substitution.</param>
-    /// <returns>The source with the token substituted inside path literals.</returns>
-    public static string SubstituteEquipmentToken(string source, string? equipBase)
+    /// <param name="scriptSource">The virtual-tag / scripted-alarm predicate script source.</param>
+    /// <returns>Distinct reference names, first-seen order; empty when none / no token.</returns>
+    public static IReadOnlyList<string> ExtractEquipReferenceNames(string? scriptSource)
    {
-        if (string.IsNullOrEmpty(source) || string.IsNullOrEmpty(equipBase)) return source;
-        if (!source.Contains(EquipToken, StringComparison.Ordinal)) return source;
-        return PathLiteralRegex.Replace(source, m =>
-            m.Groups[1].Value
-            + m.Groups[2].Value.Replace(EquipToken, equipBase, StringComparison.Ordinal)
-            + m.Groups[3].Value);
+        if (string.IsNullOrEmpty(scriptSource)
+            || !scriptSource.Contains(EquipTokenPrefix, StringComparison.Ordinal))
+            return Array.Empty<string>();
+        var seen = new HashSet<string>(StringComparer.Ordinal);
+        var result = new List<string>();
+        foreach (Match m in PathLiteralRegex.Matches(scriptSource))
+        {
+            var content = m.Groups[2].Value;
+            if (!content.StartsWith(EquipTokenPrefix, StringComparison.Ordinal)) continue;
+            var refName = content.Substring(EquipTokenPrefix.Length);
+            if (refName.Length > 0 && seen.Add(refName)) result.Add(refName);
+        }
+        return result;
+    }
+
+    /// <summary>
+    /// Distinct <c>&lt;RefName&gt;</c> values used via <c>{{equip}}/&lt;RefName&gt;</c> in FREE TEXT — the
+    /// scripted-alarm <c>MessageTemplate</c>, which is not a path literal — in first-seen order. Best-effort:
+    /// a reference name is captured up to the next whitespace / quote / brace / paren / semicolon / slash, so
+    /// a space-bearing effective name used inline in a template resolves only up to its first space (a
+    /// documented, benign limitation — template rendering is dark until Batch 4). Feeds the deploy-gate rule
+    /// for alarm message tokens.
+    /// </summary>
+    /// <param name="text">The free text (e.g. a scripted-alarm message template).</param>
+    /// <returns>Distinct reference names, first-seen order; empty when none / no token.</returns>
+    public static IReadOnlyList<string> ExtractEquipReferenceNamesFromText(string? text)
+    {
+        if (string.IsNullOrEmpty(text)
+            || !text.Contains(EquipTokenPrefix, StringComparison.Ordinal))
+            return Array.Empty<string>();
+        var seen = new HashSet<string>(StringComparer.Ordinal);
+        var result = new List<string>();
+        foreach (Match m in EquipRefTextRegex.Matches(text))
+        {
+            var refName = m.Groups[1].Value;
+            if (refName.Length > 0 && seen.Add(refName)) result.Add(refName);
+        }
+        return result;
    }

    /// <summary>
@@ -115,10 +178,11 @@ public static class EquipmentScriptPaths
    /// <c>{{equip}}</c> double-brace form is excluded by the token regex. Deterministic so the live
    /// composer (<c>AddressSpaceComposer</c>) and the artifact-decode mirror (<c>DeploymentArtifact</c>)
    /// produce the exact same ordered list — the byte-parity contract <c>EquipmentScriptedAlarmPlan</c>
-    /// equality depends on. Scripted alarms do NOT use <c>{{equip}}</c> substitution (only virtual
-    /// tags do) — pass the predicate source as-is.
+    /// equality depends on. The predicate source passed here is the ALREADY-substituted source (the two
+    /// compose seams substitute <c>{{equip}}/&lt;RefName&gt;</c> before extraction, identically), so the
+    /// merged refs are resolved RawPaths.
    /// </summary>
-    /// <param name="predicateSource">The resolved predicate script source.</param>
+    /// <param name="predicateSource">The resolved (substituted) predicate script source.</param>
    /// <param name="messageTemplate">The alarm message template carrying <c>{TagPath}</c> tokens.</param>
    /// <returns>The merged, distinct, deterministically-ordered dependency refs.</returns>
    public static IReadOnlyList<string> ExtractAlarmDependencyRefs(string? predicateSource, string? messageTemplate)
@@ -154,7 +218,7 @@ public static class EquipmentScriptPaths
    /// <param name="source">The virtual-tag script source to inspect.</param>
    /// <param name="tagReference">
    /// When the method returns <see langword="true"/>, the captured <c>GetTag</c> path literal
-    /// (e.g. <c>TestMachine_020.TestChangingInt</c> or <c>{{equip}}.Speed</c>);
+    /// (e.g. <c>TestMachine_020.TestChangingInt</c> or <c>{{equip}}/Speed</c>);
    /// otherwise <see langword="null"/>.
    /// </param>
    /// <returns>
@@ -1,197 +0,0 @@
-using LiteDB;
-
-namespace ZB.MOM.WW.OtOpcUa.Configuration.LocalCache;
-
-/// <summary>
-///     Generation-sealed LiteDB cache per <c>docs/v2/plan.md</c> and Phase 6.1
-///     Stream D.1. Each published generation writes one <b>read-only</b> LiteDB file under
-///     <c>&lt;cache-root&gt;/&lt;clusterId&gt;/&lt;generationId&gt;.db</c>. A per-cluster
-///     <c>CURRENT</c> text file holds the currently-active generation id; it is updated
-///     atomically (temp file + <see cref="File.Replace(string, string, string?)"/>) only after
-///     the sealed file is fully written.
-/// </summary>
-/// <remarks>
-///     <para>Mixed-generation reads are impossible: any read opens the single file pointed to
-///     by <c>CURRENT</c>, which is a coherent snapshot. Corruption of the CURRENT file or the
-///     sealed file surfaces as <see cref="GenerationCacheUnavailableException"/> — the reader
-///     fails closed rather than silently falling back to an older generation. Recovery path
-///     is to re-fetch from the central DB (and the Phase 6.1 Stream C <c>UsingStaleConfig</c>
-///     flag goes true until that succeeds).</para>
-///
-///     <para>This cache is the read-path fallback when the central DB is unreachable. The
-///     write path (draft edits, publish) bypasses the cache and fails hard on DB outage per
-///     Stream D.2 — inconsistent writes are worse than a temporary inability to edit.</para>
-/// </remarks>
-public sealed class GenerationSealedCache
-{
-    private const string CollectionName = "generation";
-    private const string CurrentPointerFileName = "CURRENT";
-    private readonly string _cacheRoot;
-
-    // Private per-database BsonMapper with the entity pre-registered. LiteDB's default
-    // BsonMapper.Global is a process-wide singleton whose lazy per-type member registration is
-    // not thread-safe across concurrently-constructed LiteDatabase instances; a seal racing a
-    // read (or this cache racing LiteDbConfigCache) corrupts the global mapper, surfacing as
-    // "Member … not found on BsonMapper" or a bogus duplicate-_id insert.
-    private static BsonMapper BuildMapper()
-    {
-        var mapper = new BsonMapper();
-        mapper.Entity<GenerationSnapshot>();
-        return mapper;
-    }
-
-    /// <summary>Root directory for all clusters' sealed caches.</summary>
-    public string CacheRoot => _cacheRoot;
-
-    /// <summary>Initializes a new instance of the GenerationSealedCache class.</summary>
-    /// <param name="cacheRoot">The root directory for the cache.</param>
-    public GenerationSealedCache(string cacheRoot)
-    {
-        ArgumentException.ThrowIfNullOrWhiteSpace(cacheRoot);
-        _cacheRoot = cacheRoot;
-        Directory.CreateDirectory(_cacheRoot);
-    }
-
-    /// <summary>
-    ///     Seal a generation: write the snapshot to <c>&lt;cluster&gt;/&lt;generationId&gt;.db</c>,
-    ///     mark the file read-only, then atomically publish the <c>CURRENT</c> pointer. Existing
-    ///     sealed files for prior generations are preserved (prune separately).
-    /// </summary>
-    /// <param name="snapshot">The generation snapshot to seal.</param>
-    /// <param name="ct">The cancellation token.</param>
-    /// <returns>A task representing the asynchronous operation.</returns>
-    public async Task SealAsync(GenerationSnapshot snapshot, CancellationToken ct = default)
-    {
-        ArgumentNullException.ThrowIfNull(snapshot);
-        ct.ThrowIfCancellationRequested();
-
-        var clusterDir = Path.Combine(_cacheRoot, snapshot.ClusterId);
-        Directory.CreateDirectory(clusterDir);
-        var sealedPath = Path.Combine(clusterDir, $"{snapshot.GenerationId}.db");
-
-        if (File.Exists(sealedPath))
-        {
-            // Already sealed — idempotent. Treat as no-op + update pointer in case an earlier
-            // seal succeeded but the pointer update failed (crash recovery).
-            WritePointerAtomically(clusterDir, snapshot.GenerationId);
-            return;
-        }
-
-        var tmpPath = sealedPath + ".tmp";
-        try
-        {
-            using (var db = new LiteDatabase(new ConnectionString { Filename = tmpPath, Upgrade = false }, BuildMapper()))
-            {
-                var col = db.GetCollection<GenerationSnapshot>(CollectionName);
-                col.Insert(snapshot);
-            }
-
-            File.Move(tmpPath, sealedPath);
-            File.SetAttributes(sealedPath, File.GetAttributes(sealedPath) | FileAttributes.ReadOnly);
-            WritePointerAtomically(clusterDir, snapshot.GenerationId);
-        }
-        catch
-        {
-            try { if (File.Exists(tmpPath)) File.Delete(tmpPath); } catch { /* best-effort */ }
-            throw;
-        }
-
-        await Task.CompletedTask;
-    }
-
-    /// <summary>
-    ///     Read the current sealed snapshot for <paramref name="clusterId"/>. Throws
-    ///     <see cref="GenerationCacheUnavailableException"/> when the pointer is missing
-    ///     (first-boot-no-snapshot case) or when the sealed file is corrupt. Never silently
-    ///     falls back to a prior generation.
-    /// </summary>
-    /// <param name="clusterId">The cluster ID to read the snapshot for.</param>
-    /// <param name="ct">The cancellation token.</param>
-    /// <returns>A task representing the asynchronous operation containing the generation snapshot.</returns>
-    public Task<GenerationSnapshot> ReadCurrentAsync(string clusterId, CancellationToken ct = default)
-    {
-        ArgumentException.ThrowIfNullOrWhiteSpace(clusterId);
-        ct.ThrowIfCancellationRequested();
-
-        var clusterDir = Path.Combine(_cacheRoot, clusterId);
-        var pointerPath = Path.Combine(clusterDir, CurrentPointerFileName);
-        if (!File.Exists(pointerPath))
-            throw new GenerationCacheUnavailableException(
-                $"No sealed generation for cluster '{clusterId}' at '{clusterDir}'. First-boot case: the central DB must be reachable at least once before cache fallback is possible.");
-
-        long generationId;
-        try
-        {
-            var text = File.ReadAllText(pointerPath).Trim();
-            generationId = long.Parse(text, System.Globalization.CultureInfo.InvariantCulture);
-        }
-        catch (Exception ex)
-        {
-            throw new GenerationCacheUnavailableException(
-                $"CURRENT pointer at '{pointerPath}' is corrupt or unreadable.", ex);
-        }
-
-        var sealedPath = Path.Combine(clusterDir, $"{generationId}.db");
-        if (!File.Exists(sealedPath))
-            throw new GenerationCacheUnavailableException(
-                $"CURRENT points at generation {generationId} but '{sealedPath}' is missing — fails closed rather than serving an older generation.");
-
-        try
-        {
-            using var db = new LiteDatabase(new ConnectionString { Filename = sealedPath, ReadOnly = true }, BuildMapper());
-            var col = db.GetCollection<GenerationSnapshot>(CollectionName);
-            var snapshot = col.FindAll().FirstOrDefault()
-                ?? throw new GenerationCacheUnavailableException(
-                    $"Sealed file '{sealedPath}' contains no snapshot row — file is corrupt.");
-            return Task.FromResult(snapshot);
-        }
-        catch (GenerationCacheUnavailableException) { throw; }
-        catch (Exception ex) when (ex is LiteException or InvalidDataException or IOException
-                                      or NotSupportedException or FormatException)
-        {
-            throw new GenerationCacheUnavailableException(
-                $"Sealed file '{sealedPath}' is corrupt or unreadable — fails closed rather than falling back to an older generation.", ex);
-        }
-    }
-
-    /// <summary>Return the generation id the <c>CURRENT</c> pointer points at, or null if no pointer exists.</summary>
-    /// <param name="clusterId">The cluster ID to get the current generation ID for.</param>
-    /// <returns>The generation ID, or null if no pointer exists.</returns>
-    public long? TryGetCurrentGenerationId(string clusterId)
-    {
-        ArgumentException.ThrowIfNullOrWhiteSpace(clusterId);
-        var pointerPath = Path.Combine(_cacheRoot, clusterId, CurrentPointerFileName);
-        if (!File.Exists(pointerPath)) return null;
-        try
-        {
-            return long.Parse(File.ReadAllText(pointerPath).Trim(), System.Globalization.CultureInfo.InvariantCulture);
-        }
-        catch
-        {
-            return null;
-        }
-    }
-
-    private static void WritePointerAtomically(string clusterDir, long generationId)
-    {
-        var pointerPath = Path.Combine(clusterDir, CurrentPointerFileName);
-        var tmpPath = pointerPath + ".tmp";
-        File.WriteAllText(tmpPath, generationId.ToString(System.Globalization.CultureInfo.InvariantCulture));
-        if (File.Exists(pointerPath))
-            File.Replace(tmpPath, pointerPath, destinationBackupFileName: null);
-        else
-            File.Move(tmpPath, pointerPath);
-    }
-}
-
-/// <summary>Sealed cache is unreachable — caller must fail closed.</summary>
-public sealed class GenerationCacheUnavailableException : Exception
-{
-    /// <summary>Initializes a new instance of the GenerationCacheUnavailableException class.</summary>
-    /// <param name="message">The error message.</param>
-    public GenerationCacheUnavailableException(string message) : base(message) { }
-    /// <summary>Initializes a new instance of the GenerationCacheUnavailableException class with an inner exception.</summary>
-    /// <param name="message">The error message.</param>
-    /// <param name="inner">The inner exception.</param>
-    public GenerationCacheUnavailableException(string message, Exception inner) : base(message, inner) { }
-}
@@ -1,20 +0,0 @@
-namespace ZB.MOM.WW.OtOpcUa.Configuration.LocalCache;
-
-/// <summary>
-///     A self-contained snapshot of one generation — enough to rebuild the address space on a node
-///     that has lost DB connectivity. The payload is the JSON-serialized <c>sp_GetGenerationContent</c>
-///     result; the local cache doesn't inspect the shape, it just round-trips bytes.
-/// </summary>
-public sealed class GenerationSnapshot
-{
-    /// <summary>Gets or sets the auto-generated LiteDB ID.</summary>
-    public int Id { get; set; } // LiteDB auto-ID
-    /// <summary>Gets or sets the cluster identifier.</summary>
-    public required string ClusterId { get; set; }
-    /// <summary>Gets or sets the generation identifier.</summary>
-    public required long GenerationId { get; set; }
-    /// <summary>Gets or sets the time this snapshot was cached.</summary>
-    public required DateTime CachedAt { get; set; }
-    /// <summary>Gets or sets the JSON-serialized payload content.</summary>
-    public required string PayloadJson { get; set; }
-}
@@ -1,32 +0,0 @@
-namespace ZB.MOM.WW.OtOpcUa.Configuration.LocalCache;
-
-/// <summary>
-///     Per-node local cache of the most-recently-applied generation(s). Used to bootstrap the
-///     address space when the central DB is unreachable (degraded-but-running).
-/// </summary>
-/// <remarks>
-///     <para><b>Concurrency contract:</b> implementations must serialize writes — specifically,
-///     <see cref="PutAsync"/> for the same <c>(ClusterId, GenerationId)</c> from concurrent
-///     callers must not produce duplicate rows. Reads may run concurrently with reads and writes.
-///     The <see cref="LiteDbConfigCache"/> implementation enforces this via an instance-level
-///     <see cref="SemaphoreSlim"/> around the find-then-insert/update window.</para>
-/// </remarks>
-public interface ILocalConfigCache
-{
-    /// <summary>Retrieves the most recent generation snapshot for the specified cluster.</summary>
-    /// <param name="clusterId">The cluster identifier.</param>
-    /// <param name="ct">The cancellation token.</param>
-    /// <returns>The most recent generation snapshot, or null if none exists.</returns>
-    Task<GenerationSnapshot?> GetMostRecentAsync(string clusterId, CancellationToken ct = default);
-    /// <summary>Stores a generation snapshot in the local cache.</summary>
-    /// <param name="snapshot">The generation snapshot to store.</param>
-    /// <param name="ct">The cancellation token.</param>
-    /// <returns>A task that represents the asynchronous operation.</returns>
-    Task PutAsync(GenerationSnapshot snapshot, CancellationToken ct = default);
-    /// <summary>Removes old generations, keeping only the most recent N.</summary>
-    /// <param name="clusterId">The cluster identifier.</param>
-    /// <param name="keepLatest">The number of latest generations to keep.</param>
-    /// <param name="ct">The cancellation token.</param>
-    /// <returns>A task that represents the asynchronous operation.</returns>
-    Task PruneOldGenerationsAsync(string clusterId, int keepLatest = 10, CancellationToken ct = default);
-}
@@ -1,129 +0,0 @@
-using LiteDB;
-
-namespace ZB.MOM.WW.OtOpcUa.Configuration.LocalCache;
-
-/// <summary>
-///     LiteDB-backed <see cref="ILocalConfigCache"/>. One file per node (default
-///     <c>config_cache.db</c>), one collection per snapshot. Corruption surfaces as
-///     <see cref="LocalConfigCacheCorruptException"/> on construction or read — callers should
-///     delete and re-fetch from the central DB.
-/// </summary>
-public sealed class LiteDbConfigCache : ILocalConfigCache, IDisposable
-{
-    private const string CollectionName = "generations";
-
-    // LiteDB's default BsonMapper.Global is a process-wide singleton whose per-type member
-    // registration is lazy and NOT thread-safe across concurrently-constructed LiteDatabase
-    // instances. When several caches (this one + GenerationSealedCache) initialise in parallel
-    // the global mapper races, surfacing as "Member ClusterId not found on BsonMapper" or a
-    // bogus "duplicate key _id = 0" (the int auto-id mapping was lost so Insert writes a literal
-    // 0 twice). Give each database a private, pre-registered mapper so member
-    // resolution happens once, single-threaded, at construction and never touches the global.
-    private static BsonMapper BuildMapper()
-    {
-        var mapper = new BsonMapper();
-        mapper.Entity<GenerationSnapshot>();
-        return mapper;
-    }
-
-    private readonly LiteDatabase _db;
-    private readonly ILiteCollection<GenerationSnapshot> _col;
-    // PutAsync is a find-then-insert/update; without serialization, two concurrent puts for the
-    // same (ClusterId, GenerationId) can both observe `existing is null` and both Insert,
-    // producing duplicate rows. Serialize writes through this semaphore so
-    // the read-modify-write block is atomic for a given instance. LiteDB itself only locks the
-    // page-level write, not the find-then-insert window.
-    private readonly SemaphoreSlim _writeGate = new(initialCount: 1, maxCount: 1);
-
-    /// <summary>Initializes a new instance of the <see cref="LiteDbConfigCache"/> class.</summary>
-    /// <param name="dbPath">Path to the LiteDB database file.</param>
-    public LiteDbConfigCache(string dbPath)
-    {
-        // LiteDB can be tolerant of header-only corruption at construction time (it may overwrite
-        // the header and "recover"), so we force a write + read probe to fail fast on real corruption.
-        try
-        {
-            _db = new LiteDatabase(new ConnectionString { Filename = dbPath, Upgrade = true }, BuildMapper());
-            _col = _db.GetCollection<GenerationSnapshot>(CollectionName);
-            _col.EnsureIndex(s => s.ClusterId);
-            _col.EnsureIndex(s => s.GenerationId);
-            _ = _col.Count();
-        }
-        catch (Exception ex) when (ex is LiteException or InvalidDataException or IOException
-                                      or NotSupportedException or UnauthorizedAccessException
-                                      or ArgumentOutOfRangeException or FormatException)
-        {
-            _db?.Dispose();
-            throw new LocalConfigCacheCorruptException(
-                $"LiteDB cache at '{dbPath}' is corrupt or unreadable — delete the file and refetch from the central DB.",
-                ex);
-        }
-    }
-
-    /// <inheritdoc />
-    public Task<GenerationSnapshot?> GetMostRecentAsync(string clusterId, CancellationToken ct = default)
-    {
-        ct.ThrowIfCancellationRequested();
-        var snapshot = _col
-            .Find(s => s.ClusterId == clusterId)
-            .OrderByDescending(s => s.GenerationId)
-            .FirstOrDefault();
-        return Task.FromResult<GenerationSnapshot?>(snapshot);
-    }
-
-    /// <inheritdoc />
-    public async Task PutAsync(GenerationSnapshot snapshot, CancellationToken ct = default)
-    {
-        ct.ThrowIfCancellationRequested();
-        // Serialize the find-then-insert/update so concurrent callers do not observe a stale
-        // `existing is null` and both Insert. LiteDB's per-call lock is not enough — the
-        // read and the write are independent calls.
-        await _writeGate.WaitAsync(ct).ConfigureAwait(false);
-        try
-        {
-            // upsert by (ClusterId, GenerationId) — replace in place if already cached
-            var existing = _col
-                .Find(s => s.ClusterId == snapshot.ClusterId && s.GenerationId == snapshot.GenerationId)
-                .FirstOrDefault();
-
-            if (existing is null)
-                _col.Insert(snapshot);
-            else
-            {
-                snapshot.Id = existing.Id;
-                _col.Update(snapshot);
-            }
-        }
-        finally
-        {
-            _writeGate.Release();
-        }
-    }
-
-    /// <inheritdoc />
-    public Task PruneOldGenerationsAsync(string clusterId, int keepLatest = 10, CancellationToken ct = default)
-    {
-        ct.ThrowIfCancellationRequested();
-        var doomed = _col
-            .Find(s => s.ClusterId == clusterId)
-            .OrderByDescending(s => s.GenerationId)
-            .Skip(keepLatest)
-            .Select(s => s.Id)
-            .ToList();
-
-        foreach (var id in doomed)
-            _col.Delete(id);
-
-        return Task.CompletedTask;
-    }
-
-    /// <summary>Releases all resources used by the cache.</summary>
-    public void Dispose()
-    {
-        _writeGate.Dispose();
-        _db.Dispose();
-    }
-}
-
-public sealed class LocalConfigCacheCorruptException(string message, Exception inner)
-    : Exception(message, inner);
@@ -1,140 +0,0 @@
-using System.Text.RegularExpressions;
-using Microsoft.Extensions.Logging;
-using Polly;
-using Polly.Retry;
-using Polly.Timeout;
-
-namespace ZB.MOM.WW.OtOpcUa.Configuration.LocalCache;
-
-/// <summary>
-///     Wraps a central-DB fetch function with Phase 6.1 Stream D.2 resilience:
-///     <b>timeout 2 s → retry 3× jittered → fallback to sealed cache</b>. Maintains the
-///     <see cref="StaleConfigFlag"/> — fresh on central-DB success, stale on cache fallback.
-/// </summary>
-/// <remarks>
-///     <para>Read-path only per plan. The write path (draft save, publish) bypasses this
-///     wrapper entirely and fails hard on DB outage so inconsistent writes never land.</para>
-///
-///     <para>Fallback is triggered by <b>any exception</b> the fetch raises (central-DB
-///     unreachable, SqlException, timeout). If the sealed cache also fails (no pointer,
-///     corrupt file, etc.), <see cref="GenerationCacheUnavailableException"/> surfaces — caller
-///     must fail the current request (InitializeAsync for a driver, etc.).</para>
-/// </remarks>
-public sealed class ResilientConfigReader
-{
-    private readonly GenerationSealedCache _cache;
-    private readonly StaleConfigFlag _staleFlag;
-    private readonly ResiliencePipeline _pipeline;
-    private readonly ILogger<ResilientConfigReader> _logger;
-
-    /// <summary>Initializes a resilient config reader with the given cache and options.</summary>
-    /// <param name="cache">The sealed cache for fallback.</param>
-    /// <param name="staleFlag">The stale config flag to manage.</param>
-    /// <param name="logger">The logger instance.</param>
-    /// <param name="timeout">The timeout for central fetch (default 2s).</param>
-    /// <param name="retryCount">The number of retries (default 3).</param>
-    public ResilientConfigReader(
-        GenerationSealedCache cache,
-        StaleConfigFlag staleFlag,
-        ILogger<ResilientConfigReader> logger,
-        TimeSpan? timeout = null,
-        int retryCount = 3)
-    {
-        _cache = cache;
-        _staleFlag = staleFlag;
-        _logger = logger;
-        var builder = new ResiliencePipelineBuilder()
-            .AddTimeout(new TimeoutStrategyOptions { Timeout = timeout ?? TimeSpan.FromSeconds(2) });
-
-        if (retryCount > 0)
-        {
-            builder.AddRetry(new RetryStrategyOptions
-            {
-                MaxRetryAttempts = retryCount,
-                BackoffType = DelayBackoffType.Exponential,
-                UseJitter = true,
-                Delay = TimeSpan.FromMilliseconds(100),
-                MaxDelay = TimeSpan.FromSeconds(1),
-                // Handle ALL exceptions including OperationCanceledException. A SQL command-level
-                // timeout surfaces as TaskCanceledException (derives from OperationCanceledException)
-                // when the caller's token is NOT cancelled, and must be retried just like any other
-                // transient error. Polly itself checks the cancellation token between retries and
-                // stops with OperationCanceledException on genuine caller cancellation regardless of
-                // this predicate.
-                ShouldHandle = new PredicateBuilder().Handle<Exception>(),
-            });
-        }
-
-        _pipeline = builder.Build();
-    }
-
-    /// <summary>
-    ///     Redacts connection-string fragments (Password, User Id, Pwd, etc.)
-    ///     that a caller's exception message could carry. Conservative regex pass — anything
-    ///     matching <c>Key=Value</c> with a known credential key gets its value replaced.
-    /// </summary>
-    private static readonly Regex SecretsRegex = new(
-        @"(?ix)\b(Password|Pwd|User\s*Id|Uid|AccessToken|Authorization|Api[-_]?Key)\s*=\s*[^;,)\s]*",
-        RegexOptions.Compiled);
-
-    /// <summary>Redacts sensitive credential information from a message.</summary>
-    /// <param name="message">The message to scrub.</param>
-    /// <returns>The message with redacted credentials.</returns>
-    internal static string ScrubSecrets(string? message)
-    {
-        if (string.IsNullOrEmpty(message)) return message ?? string.Empty;
-        // Replace the entire matched fragment (key + value) with a redaction marker so the
-        // key name itself doesn't leak — log scrapers grep for "Password=" too.
-        return SecretsRegex.Replace(message, "[redacted credential]");
-    }
-
-    /// <summary>
-    ///     Executes a central fetch through the resilience pipeline. On full failure
-    ///     (post-retry), reads the sealed cache and extracts the requested shape.
-    /// </summary>
-    /// <typeparam name="T">The type of configuration to read.</typeparam>
-    /// <param name="clusterId">The cluster ID to fetch for.</param>
-    /// <param name="centralFetch">Function to fetch from central DB.</param>
-    /// <param name="fromSnapshot">Function to extract the config from a snapshot.</param>
-    /// <param name="cancellationToken">Cancellation token.</param>
-    /// <returns>The configuration of type T.</returns>
-    public async ValueTask<T> ReadAsync<T>(
-        string clusterId,
-        Func<CancellationToken, ValueTask<T>> centralFetch,
-        Func<GenerationSnapshot, T> fromSnapshot,
-        CancellationToken cancellationToken)
-    {
-        ArgumentException.ThrowIfNullOrWhiteSpace(clusterId);
-        ArgumentNullException.ThrowIfNull(centralFetch);
-        ArgumentNullException.ThrowIfNull(fromSnapshot);
-
-        try
-        {
-            var result = await _pipeline.ExecuteAsync(centralFetch, cancellationToken).ConfigureAwait(false);
-            _staleFlag.MarkFresh();
-            return result;
-        }
-        // Catch all exceptions that are NOT genuine caller cancellations. A SQL command-level
-        // timeout surfaces as TaskCanceledException (derives from OperationCanceledException)
-        // but the caller's token is NOT cancelled — we must fall back to the sealed cache for
-        // that case, not propagate. Only rethrow if the caller actually requested cancellation.
-        catch (Exception ex) when (ex is not OperationCanceledException || !cancellationToken.IsCancellationRequested)
-        {
-            // Do NOT pass the raw exception object — it carries the stack
-            // and inner-exception chain, and SqlException/wrapping delegates can surface
-            // connection-string fragments (Password=…, User Id=…) embedded in messages.
-            // Log only the exception type and a scrubbed message so secrets stay out of logs.
-            _logger.LogWarning(
-                "Central-DB read failed after retries ({ExceptionType}: {SanitizedMessage}); falling back to sealed cache for cluster {ClusterId}",
-                ex.GetType().Name,
-                ScrubSecrets(ex.Message),
-                clusterId);
-            // GenerationCacheUnavailableException surfaces intentionally — fails the caller's
-            // operation. StaleConfigFlag stays unchanged; the flag only flips when we actually
-            // served a cache snapshot.
-            var snapshot = await _cache.ReadCurrentAsync(clusterId, cancellationToken).ConfigureAwait(false);
-            _staleFlag.MarkStale();
-            return fromSnapshot(snapshot);
-        }
-    }
-}
@@ -1,20 +0,0 @@
-namespace ZB.MOM.WW.OtOpcUa.Configuration.LocalCache;
-
-/// <summary>
-///     Thread-safe <c>UsingStaleConfig</c> signal per Phase 6.1 Stream D.3. Flips true whenever
-///     a read falls back to a sealed cache snapshot; flips false on the next successful central-DB
-///     round-trip. Surfaced on <c>/healthz</c> body and on the Admin <c>/hosts</c> page.
-/// </summary>
-public sealed class StaleConfigFlag
-{
-    private int _stale;
-
-    /// <summary>True when the last config read was served from the sealed cache, not the central DB.</summary>
-    public bool IsStale => Volatile.Read(ref _stale) != 0;
-
-    /// <summary>Mark the current config as stale (a read fell back to the cache).</summary>
-    public void MarkStale() => Volatile.Write(ref _stale, 1);
-
-    /// <summary>Mark the current config as fresh (a central-DB read succeeded).</summary>
-    public void MarkFresh() => Volatile.Write(ref _stale, 0);
-}
@@ -10,10 +10,18 @@ namespace ZB.MOM.WW.OtOpcUa.Configuration.Services;
 ///     Phase 6.2 compliance check on control/data-plane separation).
 /// </summary>
 /// <remarks>
-///     Per Phase 6.2 Stream A.2 this service is expected to run behind the Phase 6.1
-///     <c>ResilientConfigReader</c> pipeline (timeout → retry → fallback-to-cache) so a
-///     transient DB outage during sign-in falls back to the sealed snapshot rather than
-///     denying every login.
+///     <para>
+///         This service has no local-cache fallback: a DB outage during sign-in denies logins.
+///     </para>
+///     <para>
+///         The Phase 6.1 <c>ResilientConfigReader</c> pipeline (timeout → retry →
+///         fallback-to-sealed-snapshot) this was once expected to run behind was never wired to
+///         anything and was deleted along with the rest of the dormant LiteDB local cache, which
+///         <c>ZB.MOM.WW.LocalDb</c> supersedes. LocalDb caches the deployed-configuration artifact
+///         for driver-role nodes; it does not currently cover admin-plane reads like this one.
+///         Reviving the fallback means adding an admin-side cache on LocalDb, not restoring the
+///         old pipeline.
+///     </para>
 /// </remarks>
 public interface ILdapGroupRoleMappingService
 {
@@ -55,6 +55,10 @@ public sealed class DraftSnapshot
    public IReadOnlyList<VirtualTag> VirtualTags { get; init; } = [];
    /// <summary>Equipment-bound scripted alarms. Part of the UNS effective-leaf uniqueness set.</summary>
    public IReadOnlyList<ScriptedAlarm> ScriptedAlarms { get; init; } = [];
+
+    /// <summary>User-authored scripts (shared by VirtualTags, ScriptedAlarms, and Calculation tags). Drives
+    /// the WP7 Calculation gates: <c>scriptId</c> existence + the calc→calc dependency-cycle check.</summary>
+    public IReadOnlyList<Script> Scripts { get; init; } = [];
    /// <summary>Gets the list of poll groups.</summary>
    public IReadOnlyList<PollGroup> PollGroups { get; init; } = [];

@@ -50,6 +50,7 @@ public static class DraftSnapshotFactory
            UnsTagReferences   = await db.UnsTagReferences.AsNoTracking().ToListAsync(ct),
            VirtualTags        = await db.VirtualTags.AsNoTracking().ToListAsync(ct),
            ScriptedAlarms     = await db.ScriptedAlarms.AsNoTracking().ToListAsync(ct),
+            Scripts            = await db.Scripts.AsNoTracking().ToListAsync(ct),
            PollGroups         = await db.PollGroups.AsNoTracking().ToListAsync(ct),
            PriorEquipment     = [],   // intentional: no prior-generation table to diff against at this level
            ActiveReservations = await db.ExternalIdReservations
@@ -2,6 +2,7 @@ using System.Text.RegularExpressions;
 using ZB.MOM.WW.OtOpcUa.Commons.Types;
 using ZB.MOM.WW.OtOpcUa.Configuration.Entities;
 using ZB.MOM.WW.OtOpcUa.Configuration.Enums;
+using ZB.MOM.WW.OtOpcUa.Core.VirtualTags;

 namespace ZB.MOM.WW.OtOpcUa.Configuration.Validation;

@@ -38,9 +39,108 @@ public static class DraftValidator
        ValidateRawNameCharset(draft, errors);
        ValidateHistorizedTagnameLength(draft, errors);
        ValidateUnsEffectiveLeafUniqueness(draft, errors);
+        ValidateEquipReferenceResolution(draft, errors);
+        ValidateCalculationTags(draft, errors);
        return errors;
    }

+    /// <summary>WP7 Calculation-driver deploy gates. For every tag bound to a <c>Calculation</c> driver:
+    /// <list type="number">
+    ///   <item><b>scriptId existence</b> — the tag's <c>TagConfig.scriptId</c> must be present and resolve to
+    ///     a <see cref="Script"/> row in the draft.</item>
+    ///   <item><b>Cycle gate (hard error)</b> — build the calc→calc edge set (a calc tag → its
+    ///     <c>ctx.GetTag</c> deps that are <b>themselves</b> Calculation tags; cross-driver refs are terminal,
+    ///     not edges) and run <see cref="DependencyGraph.DetectCycles"/> (Tarjan SCC). Any SCC / self-loop is a
+    ///     deploy error naming the cycle members — an undetected calc cycle is a live oscillation loop.</item>
+    /// </list>
+    /// Compile is deliberately NOT hard-gated (VirtualTag parity — the editor's live diagnostics mirror it and
+    /// a runtime compile failure lands as Bad quality + a script-log).</summary>
+    private static void ValidateCalculationTags(DraftSnapshot draft, List<ValidationError> errors)
+    {
+        var driverTypeByInstance = draft.DriverInstances
+            .GroupBy(d => d.DriverInstanceId, StringComparer.Ordinal)
+            .ToDictionary(g => g.Key, g => g.First().DriverType, StringComparer.Ordinal);
+        var driverTypeByDevice = draft.Devices
+            .GroupBy(d => d.DeviceId, StringComparer.Ordinal)
+            .ToDictionary(
+                g => g.Key,
+                g => driverTypeByInstance.TryGetValue(g.First().DriverInstanceId, out var dt) ? dt : null,
+                StringComparer.Ordinal);
+
+        var resolver = BuildRawPathResolver(draft);
+        var scriptExists = new HashSet<string>(draft.Scripts.Select(s => s.ScriptId), StringComparer.Ordinal);
+        var scriptSourceById = draft.Scripts
+            .GroupBy(s => s.ScriptId, StringComparer.Ordinal)
+            .ToDictionary(g => g.Key, g => g.First().SourceCode, StringComparer.Ordinal);
+
+        // Identify calc tags (tags on a Calculation-typed device) + their RawPath + scriptId in one pass.
+        var calcTags = new List<(Tag Tag, string? RawPath, string? ScriptId)>();
+        var calcRawPaths = new HashSet<string>(StringComparer.Ordinal);
+        foreach (var t in draft.Tags)
+        {
+            if (!driverTypeByDevice.TryGetValue(t.DeviceId, out var dt)
+                || !string.Equals(dt, Core.Abstractions.DriverTypeNames.Calculation, StringComparison.Ordinal))
+                continue;
+            var rawPath = resolver.TryBuildTagPath(t.DeviceId, t.TagGroupId, t.Name);
+            calcTags.Add((t, rawPath, ParseScriptId(t.TagConfig)));
+            if (rawPath is not null) calcRawPaths.Add(rawPath);
+        }
+        if (calcTags.Count == 0) return;
+
+        // Rule 1 — scriptId existence.
+        foreach (var (t, _, scriptId) in calcTags)
+        {
+            if (string.IsNullOrWhiteSpace(scriptId))
+                errors.Add(new("CalculationScriptMissing",
+                    $"Calculation tag '{t.TagId}' has no 'scriptId' in its TagConfig", t.TagId));
+            else if (!scriptExists.Contains(scriptId!))
+                errors.Add(new("CalculationScriptNotFound",
+                    $"Calculation tag '{t.TagId}' references script '{scriptId}', which does not exist in the draft",
+                    t.TagId));
+        }
+
+        // Rule 2 — cycle gate. Edges run from a calc tag to each dep that is ITSELF a calc tag.
+        var graph = new DependencyGraph();
+        foreach (var (_, rawPath, scriptId) in calcTags)
+        {
+            if (rawPath is null) continue; // broken chain — flagged by the charset rule; not a graph node
+            var source = scriptId is not null && scriptSourceById.TryGetValue(scriptId, out var src) ? src : null;
+            var calcDeps = EquipmentScriptPaths.ExtractDependencyRefs(source)
+                .Where(calcRawPaths.Contains)
+                .ToHashSet(StringComparer.Ordinal);
+            graph.Add(rawPath, calcDeps);
+        }
+        foreach (var cycle in graph.DetectCycles())
+            errors.Add(new("CalculationDependencyCycle",
+                "Calculation tags form a dependency cycle (members: " + string.Join(", ", cycle) +
+                "); a calc→calc cycle is a live oscillation loop and must be broken before deploy",
+                cycle.Count > 0 ? cycle[0] : null));
+    }
+
+    /// <summary>Extract the <c>scriptId</c> string from a calc tag's schemaless <c>TagConfig</c> JSON. Never
+    /// throws — malformed/blank/non-object JSON or an absent/non-string <c>scriptId</c> yields null.</summary>
+    private static string? ParseScriptId(string? tagConfig)
+    {
+        if (string.IsNullOrWhiteSpace(tagConfig)) return null;
+        try
+        {
+            using var doc = System.Text.Json.JsonDocument.Parse(tagConfig);
+            var root = doc.RootElement;
+            if (root.ValueKind != System.Text.Json.JsonValueKind.Object) return null;
+            if (root.TryGetProperty("scriptId", out var el)
+                && el.ValueKind == System.Text.Json.JsonValueKind.String)
+            {
+                var v = el.GetString();
+                return string.IsNullOrWhiteSpace(v) ? null : v;
+            }
+            return null;
+        }
+        catch (System.Text.Json.JsonException)
+        {
+            return null;
+        }
+    }
+
    /// <summary>Builds the shared <see cref="RawPathResolver"/> from the draft's raw topology so the
    /// tagname-length rule computes the SAME RawPath the deploy artifact injects into drivers.</summary>
    private static RawPathResolver BuildRawPathResolver(DraftSnapshot draft)
@@ -139,6 +239,64 @@ public static class DraftValidator
        }
    }

+    /// <summary>v3: every <c>{{equip}}/&lt;RefName&gt;</c> used in an equipment's VirtualTag script,
+    /// ScriptedAlarm predicate script, or ScriptedAlarm message template must resolve to one of the owning
+    /// equipment's <c>UnsTagReference</c> effective names (<c>DisplayNameOverride</c> else the backing raw
+    /// tag's <c>Name</c>) — the same set the compose seams substitute against. An unresolved <c>&lt;RefName&gt;</c>
+    /// is a deploy error (replacing the v2 silent null-base no-substitution), naming the script/alarm, the
+    /// equipment, and the missing ref. This is the deploy-gate half of the invariant the Monaco diagnostic +
+    /// the authoring gate enforce (editor accepts ⇔ publish accepts).</summary>
+    private static void ValidateEquipReferenceResolution(DraftSnapshot draft, List<ValidationError> errors)
+    {
+        var tagNameById = draft.Tags.GroupBy(t => t.TagId, StringComparer.Ordinal)
+            .ToDictionary(g => g.Key, g => g.First().Name, StringComparer.Ordinal);
+
+        // equipmentId → set of reference effective names ({{equip}}/<RefName> resolves through REFERENCES
+        // only — VirtualTags/ScriptedAlarms are computed signals with no backing RawPath).
+        var refNamesByEquip = new Dictionary<string, HashSet<string>>(StringComparer.Ordinal);
+        foreach (var r in draft.UnsTagReferences)
+        {
+            var effective = r.DisplayNameOverride ?? (tagNameById.TryGetValue(r.TagId, out var n) ? n : null);
+            if (string.IsNullOrEmpty(effective)) continue;
+            if (!refNamesByEquip.TryGetValue(r.EquipmentId, out var set))
+                refNamesByEquip[r.EquipmentId] = set = new HashSet<string>(StringComparer.Ordinal);
+            set.Add(effective!);
+        }
+
+        var scriptSourceById = draft.Scripts.GroupBy(s => s.ScriptId, StringComparer.Ordinal)
+            .ToDictionary(g => g.Key, g => g.First().SourceCode, StringComparer.Ordinal);
+
+        void CheckRefs(string equipmentId, IEnumerable<string> refNames, string source)
+        {
+            var have = refNamesByEquip.TryGetValue(equipmentId, out var set) ? set : null;
+            foreach (var name in refNames)
+            {
+                if (have is not null && have.Contains(name)) continue;
+                errors.Add(new("EquipReferenceUnresolved",
+                    $"{source} uses '{EquipmentScriptPaths.EquipTokenPrefix}{name}' but equipment '{equipmentId}' has " +
+                    $"no reference named '{name}'; add a reference with that effective name or correct the script.",
+                    equipmentId));
+            }
+        }
+
+        foreach (var v in draft.VirtualTags)
+        {
+            var src = scriptSourceById.TryGetValue(v.ScriptId, out var s) ? s : null;
+            var used = EquipmentScriptPaths.ExtractEquipReferenceNames(src);
+            if (used.Count > 0) CheckRefs(v.EquipmentId, used, $"VirtualTag '{v.VirtualTagId}'");
+        }
+
+        foreach (var a in draft.ScriptedAlarms)
+        {
+            var src = scriptSourceById.TryGetValue(a.PredicateScriptId, out var s) ? s : null;
+            var used = EquipmentScriptPaths.ExtractEquipReferenceNames(src)
+                .Concat(EquipmentScriptPaths.ExtractEquipReferenceNamesFromText(a.MessageTemplate))
+                .Distinct(StringComparer.Ordinal)
+                .ToList();
+            if (used.Count > 0) CheckRefs(a.EquipmentId, used, $"ScriptedAlarm '{a.ScriptedAlarmId}'");
+        }
+    }
+
    private static bool IsValidSegment(string? s) =>
        s is not null && (UnsSegment.IsMatch(s) || s == UnsDefaultSegment);

@@ -7,7 +7,12 @@
        <LangVersion>latest</LangVersion>
        <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
        <GenerateDocumentationFile>true</GenerateDocumentationFile>
-        <NoWarn>$(NoWarn);CS1591</NoWarn>
+        <!-- WP7: the calc deploy-gate reuses the pure DependencyGraph (Tarjan SCC) from Core.VirtualTags,
+             whose closure includes Microsoft.CodeAnalysis.CSharp.Scripting 4.12.0 (== CodeAnalysis.Common
+             4.12.0), while EF's transitive CodeAnalysis.Common 5.0.0 wins resolution. Suppress NU1608 — the
+             only surface Configuration touches (DependencyGraph.DetectCycles) has ZERO Roslyn dependency, so
+             the version skew never runs. Mirrors the identical suppression + rationale in the Host csproj. -->
+        <NoWarn>$(NoWarn);CS1591;NU1608</NoWarn>
        <RootNamespace>ZB.MOM.WW.OtOpcUa.Configuration</RootNamespace>
    </PropertyGroup>

@@ -21,7 +26,6 @@
        <PackageReference Include="Microsoft.AspNetCore.DataProtection.EntityFrameworkCore"/>
        <PackageReference Include="Microsoft.Extensions.Configuration.Abstractions"/>
        <PackageReference Include="Microsoft.Extensions.Logging.Abstractions"/>
-        <PackageReference Include="LiteDB"/>
        <PackageReference Include="Polly.Core"/>
    </ItemGroup>

@@ -30,6 +34,9 @@
        <!-- R2-11 (01/C-1): consume the shared TagConfigIntent.Parse byte-parity authority in Commons.
             Cycle-safe — Commons has zero in-repo ProjectReferences. -->
        <ProjectReference Include="..\ZB.MOM.WW.OtOpcUa.Commons\ZB.MOM.WW.OtOpcUa.Commons.csproj"/>
+        <!-- WP7: the deploy-gate cycle check reuses DependencyGraph (Tarjan SCC) for the calc→calc
+             dependency-cycle rule. Cycle-safe — Core.VirtualTags does not reference Configuration. -->
+        <ProjectReference Include="..\ZB.MOM.WW.OtOpcUa.Core.VirtualTags\ZB.MOM.WW.OtOpcUa.Core.VirtualTags.csproj"/>
    </ItemGroup>

 </Project>
@@ -0,0 +1,72 @@
+namespace ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+
+/// <summary>
+///     Single source of truth for the driver-type identifier strings the runtime
+///     dispatches on. Each constant's <b>value</b> is the exact <c>DriverTypeName</c>
+///     that the corresponding driver factory registers under in the process
+///     <c>DriverFactoryRegistry</c> — the string the deploy pipeline stores in
+///     <c>DriverInstance.DriverType</c> and every dispatch map keys by.
+/// </summary>
+/// <remarks>
+///     <para>
+///     Historically several dispatch maps hand-authored these strings and drifted from
+///     the authoritative factory names (e.g. <c>"TwinCat"</c> vs the real
+///     <c>"TwinCAT"</c>, <c>"Focas"</c> vs <c>"FOCAS"</c>). Consumers should reference
+///     these constants instead of literals so the drift can never recur.
+///     </para>
+///     <para>
+///     The reflection guard test
+///     (<c>DriverTypeNamesGuardTests</c>) asserts bidirectional parity between these
+///     constants and the set the driver factories actually register, so a rename on
+///     either side breaks the build's test gate. Only constants for
+///     <b>currently-registered</b> factories belong here — a not-yet-registered driver
+///     (e.g. the Calculation driver landing in a later Batch 2 package) adds its own
+///     constant when its factory is wired in.
+///     </para>
+/// </remarks>
+public static class DriverTypeNames
+{
+    /// <summary>Modbus TCP / RTU-over-TCP driver.</summary>
+    public const string Modbus = "Modbus";
+
+    /// <summary>Siemens S7 driver.</summary>
+    public const string S7 = "S7";
+
+    /// <summary>Allen-Bradley CIP (ControlLogix / CompactLogix) driver.</summary>
+    public const string AbCip = "AbCip";
+
+    /// <summary>Allen-Bradley legacy (PCCC / DF1-over-TCP) driver.</summary>
+    public const string AbLegacy = "AbLegacy";
+
+    /// <summary>Beckhoff TwinCAT ADS driver.</summary>
+    public const string TwinCAT = "TwinCAT";
+
+    /// <summary>FANUC FOCAS CNC driver.</summary>
+    public const string FOCAS = "FOCAS";
+
+    /// <summary>OPC UA client (upstream-server) driver.</summary>
+    public const string OpcUaClient = "OpcUaClient";
+
+    /// <summary>AVEVA System Platform (Wonderware) Galaxy driver, via the mxaccessgw gateway.</summary>
+    public const string Galaxy = "GalaxyMxGateway";
+
+    /// <summary>Calculation pseudo-driver — tags computed by C# scripts over other tags' live values.</summary>
+    public const string Calculation = "Calculation";
+
+    /// <summary>
+    ///     Every driver-type string declared above, for callers that need to enumerate
+    ///     the full set (e.g. validation of an authored <c>DriverType</c>).
+    /// </summary>
+    public static IReadOnlyCollection<string> All { get; } =
+    [
+        Modbus,
+        S7,
+        AbCip,
+        AbLegacy,
+        TwinCAT,
+        FOCAS,
+        OpcUaClient,
+        Galaxy,
+        Calculation,
+    ];
+}
@@ -0,0 +1,44 @@
+namespace ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+
+/// <summary>
+///     Optional composable driver capability: the driver consumes <b>other</b> tags' live values.
+///     The host registers the declared <see cref="DependencyRefs"/> with its per-node dependency mux
+///     and forwards every matching value change into <see cref="OnDependencyValue"/> — the seam that
+///     lets a host-blind driver (e.g. the <c>Calculation</c> pseudo-driver) read the address space's
+///     live values without any cross-driver plumbing of its own.
+/// </summary>
+/// <remarks>
+///     <para>
+///         The mechanism mirrors how a <c>VirtualTagActor</c> registers interest on the
+///         <c>DependencyMuxActor</c>: the mux already receives every driver's
+///         <c>AttributeValuePublished</c> keyed by wire-ref (under v3, RawPath), so a driver that
+///         implements this interface simply piggy-backs on that fan-out. A calc tag's computed output
+///         re-enters the mux via the ordinary driver publish path, so calc-of-calc chains work with no
+///         extra machinery — which is exactly why the deploy-time cycle gate is mandatory.
+///     </para>
+///     <para>
+///         Implementations of <see cref="OnDependencyValue"/> are invoked from an actor context and
+///         <b>must be non-blocking</b> — do the work inline and cheaply (the compile cache makes
+///         steady-state calc evaluation a bounded method invocation), never block on I/O.
+///     </para>
+/// </remarks>
+public interface IDependencyConsumer
+{
+    /// <summary>
+    ///     Wire-refs (RawPaths) this driver needs fed to it, derived from its authored tags. The host
+    ///     re-reads this after <see cref="IDriver.InitializeAsync"/> / <see cref="IDriver.ReinitializeAsync"/>
+    ///     and (re)registers the set with its dependency mux on every apply, so a tag/script edit that
+    ///     changes the set converges without a bespoke notification.
+    /// </summary>
+    IReadOnlyCollection<string> DependencyRefs { get; }
+
+    /// <summary>
+    ///     Host push of a single dependency value change. Called from an actor context, so the
+    ///     implementation must be non-blocking.
+    /// </summary>
+    /// <param name="rawPath">The changed dependency's wire-ref (RawPath).</param>
+    /// <param name="value">The new value (may be null).</param>
+    /// <param name="statusCode">The OPC UA status code carried with the value (0 = Good).</param>
+    /// <param name="timestampUtc">The source timestamp of the change.</param>
+    void OnDependencyValue(string rawPath, object? value, uint statusCode, DateTime timestampUtc);
+}
@@ -377,4 +377,9 @@ public enum EmissionKind
    Enabled,
    Disabled,
    CommentAdded,
+    /// <summary>#478 — the worst-of-input source quality changed bucket (Good/Uncertain/Bad) with no
+    /// accompanying Part 9 state transition. Delivered out of band via the dedicated
+    /// <c>WriteAlarmQuality</c> node path, never through the <c>IAlarmSource</c> fan-out (it is not a
+    /// state change and must not materialize or historize a condition).</summary>
+    QualityChanged,
 }
@@ -62,6 +62,17 @@ public sealed class ScriptedAlarmEngine : IDisposable
    private readonly ConcurrentDictionary<string, AlarmScratch> _scratchByAlarmId =
        new(StringComparer.Ordinal);

+    /// <summary>
+    ///     #478 — last emitted worst-of-input quality bucket per alarm (0 = Good, 1 = Uncertain,
+    ///     2 = Bad), computed each evaluation over the refilled read cache. A change in this bucket
+    ///     with no accompanying Part 9 state transition drives a standalone
+    ///     <see cref="EmissionKind.QualityChanged"/> emission (a Bad input freezes the condition — no
+    ///     transition — so quality can't ride one, exactly like a comms-lost native driver). Only ever
+    ///     mutated under <c>_evalGate</c>; cleared alongside <see cref="_alarms"/> on load/dispose.
+    /// </summary>
+    private readonly ConcurrentDictionary<string, int> _lastQualityBucketByAlarmId =
+        new(StringComparer.Ordinal);
+
    /// <summary>
    ///     Compile cache for every alarm predicate. Routes <see cref="LoadAsync"/>'s
    ///     <see cref="ScriptEvaluator{TContext, TResult}.Compile"/> calls through the
@@ -203,6 +214,7 @@ public sealed class ScriptedAlarmEngine : IDisposable
            // have changed (different Inputs, different Logger), so any reuse would be
            // unsafe.
            _scratchByAlarmId.Clear();
+            _lastQualityBucketByAlarmId.Clear();
            // Dispose every compiled-predicate ALC from the prior generation BEFORE we
            // recompile this one. Skipping this is what made the earlier fix a
            // no-op in production.
@@ -412,7 +424,7 @@ public sealed class ScriptedAlarmEngine : IDisposable
            // OnEvent dispatch until after Release() so a slow subscriber or a
            // subscriber that re-enters the engine doesn't block / deadlock.
            if (result.Emission != EmissionKind.None)
-                pending = BuildEmission(state, result.State, result.Emission);
+                pending = BuildEmission(state, result.State, result.Emission, LastWorstStatus(alarmId));
            else if (result.NoOpReason is { } reason)
            {
                // The Part9StateMachine remarks promise a diagnostic log line for
@@ -513,13 +525,27 @@ public sealed class ScriptedAlarmEngine : IDisposable
            _ => new AlarmScratch(state.Inputs, state.Logger, _clock));
        RefillReadCache(scratch.ReadCache, state.Inputs);

+        // #478 — worst OPC UA quality across the alarm's inputs, computed BEFORE the readiness
+        // short-circuit so an outright-Bad input is still observed. A bucket change with no state
+        // transition is delivered out of band as a QualityChanged emission (see below).
+        var worstStatus = WorstInputStatus(scratch.ReadCache);
+        var qualityBucketChanged = TrackQualityBucket(state.Definition.AlarmId, worstStatus);
+
        // Cold-start guard — skip the predicate when any referenced upstream tag has no
        // cached value yet (the upstream subscription hasn't delivered its first push).
        // Without this, predicates that cast `(double)ctx.GetTag(path).Value` throw NRE on
        // every tick until the cache fills, spamming the log with identical stack traces.
        // Bad quality is treated the same: the input isn't available at the predicate's
        // expected type, so the only defensible move is to hold the prior condition state.
-        if (!AreInputsReady(scratch.ReadCache)) return seed;
+        if (!AreInputsReady(scratch.ReadCache))
+        {
+            // The condition is frozen (can't trust its state), but its source quality just changed
+            // bucket — annotate it out of band so a comms-lost / Bad-input scripted condition reports
+            // Bad, mirroring the native OT path.
+            if (qualityBucketChanged)
+                pendingEmissions.Add(BuildQualityEmission(state, seed, worstStatus));
+            return seed;
+        }

        var context = scratch.Context;

@@ -544,10 +570,19 @@ public sealed class ScriptedAlarmEngine : IDisposable
        }

        var result = Part9StateMachine.ApplyPredicate(seed, predicateTrue, nowUtc);
-        if (result.Emission != EmissionKind.None)
+        var transition = result.Emission != EmissionKind.None
+            ? BuildEmission(state, result.State, result.Emission, worstStatus)
+            : null;
+        if (transition is not null)
        {
-            var evt = BuildEmission(state, result.State, result.Emission);
-            if (evt is not null) pendingEmissions.Add(evt);
+            // A real transition carries the current worst quality so the projected full-snapshot
+            // write doesn't clobber quality back to Good (e.g. a transition while an input is Uncertain).
+            pendingEmissions.Add(transition);
+        }
+        else if (qualityBucketChanged)
+        {
+            // No transition (or a Suppressed one) but the quality bucket moved — annotate out of band.
+            pendingEmissions.Add(BuildQualityEmission(state, result.State, worstStatus));
        }
        return result.State;
    }
@@ -599,7 +634,8 @@ public sealed class ScriptedAlarmEngine : IDisposable
    ///     done by <see cref="FireEvent(ScriptedAlarmEvent)"/> AFTER the gate is
    ///     released.
    /// </summary>
-    private ScriptedAlarmEvent? BuildEmission(AlarmState state, AlarmConditionState condition, EmissionKind kind)
+    private ScriptedAlarmEvent? BuildEmission(
+        AlarmState state, AlarmConditionState condition, EmissionKind kind, uint worstInputStatus)
    {
        // Suppressed kind means shelving ate the emission — we don't fire for subscribers
        // but the state record still advanced so startup recovery reflects reality.
@@ -629,9 +665,89 @@ public sealed class ScriptedAlarmEngine : IDisposable
            // Carry the per-alarm durable-historization opt-out through to subscribers. The historian
            // adapter honors it to suppress ONLY the durable sink write; the live alerts fan-out is
            // unaffected (it is not gated on this flag).
-            HistorizeToAveva: state.Definition.HistorizeToAveva);
+            HistorizeToAveva: state.Definition.HistorizeToAveva,
+            // #478 — the worst input quality at evaluation time rides the transition so the projected
+            // full snapshot keeps quality consistent (no clobber-to-Good).
+            WorstInputStatusCode: worstInputStatus);
    }

+    /// <summary>
+    ///     #478 — build a standalone <see cref="EmissionKind.QualityChanged"/> event carrying the new
+    ///     worst-of-input quality. Emitted when the quality bucket moved but no Part 9 transition fired
+    ///     (a Bad input freezes the condition; a Suppressed/None transition also leaves state unchanged).
+    ///     The host routes it to the dedicated <c>WriteAlarmQuality</c> node path (annotate quality only,
+    ///     no <c>/alerts</c> row, no historian write); the <see cref="IAlarmSource"/> fan-out skips it.
+    /// </summary>
+    private ScriptedAlarmEvent BuildQualityEmission(
+        AlarmState state, AlarmConditionState condition, uint worstInputStatus)
+        => new(
+            AlarmId: state.Definition.AlarmId,
+            EquipmentPath: state.Definition.EquipmentPath,
+            AlarmName: state.Definition.AlarmName,
+            Kind: state.Definition.Kind,
+            Severity: state.Definition.Severity,
+            Message: MessageTemplate.Resolve(state.Definition.MessageTemplate, TryLookup),
+            Condition: condition,
+            Emission: EmissionKind.QualityChanged,
+            TimestampUtc: _clock(),
+            HistorizeToAveva: state.Definition.HistorizeToAveva,
+            WorstInputStatusCode: worstInputStatus);
+
+    /// <summary>Worst OPC UA StatusCode across a refilled read cache — the entry with the highest severity
+    /// bits (top 2). An input with no value yet (null snapshot/value — the cold-start placeholder, or a
+    /// not-yet-published upstream) is NOT a quality signal: it means "no data", which the
+    /// <see cref="AreInputsReady"/> guard already handles by holding the condition. Counting it as Bad here
+    /// would flash every scripted condition Bad at deploy until the first push and would flood the quality
+    /// path with load-time annotations, so unread inputs are skipped (contribute Good). Empty / all-unread
+    /// cache ⇒ Good (0).</summary>
+    private static uint WorstInputStatus(IReadOnlyDictionary<string, DataValueSnapshot> cache)
+    {
+        uint worst = 0u;
+        var worstSeverity = 0u;
+        foreach (var kv in cache)
+        {
+            if (kv.Value is null || kv.Value.Value is null) continue; // no data yet — not a quality signal
+            var status = kv.Value.StatusCode;
+            var severity = status >> 30;
+            if (severity > worstSeverity)
+            {
+                worstSeverity = severity;
+                worst = status;
+            }
+        }
+        return worst;
+    }
+
+    /// <summary>Update the tracked worst-quality bucket for an alarm; return true iff the 3-state bucket
+    /// (0 = Good, 1 = Uncertain, 2 = Bad) changed from the last observed value. Only called under
+    /// <c>_evalGate</c>.</summary>
+    private bool TrackQualityBucket(string alarmId, uint worstStatus)
+    {
+        var bucket = QualityBucket(worstStatus);
+        var prior = _lastQualityBucketByAlarmId.TryGetValue(alarmId, out var b) ? b : 0; // default Good
+        _lastQualityBucketByAlarmId[alarmId] = bucket;
+        return bucket != prior;
+    }
+
+    /// <summary>Collapse an OPC UA StatusCode's 2 severity bits (00/01/10/11) to a 3-state quality bucket
+    /// (0 = Good, 1 = Uncertain, 2 = Bad).</summary>
+    private static int QualityBucket(uint statusCode)
+    {
+        var severity = statusCode >> 30;
+        return severity >= 2 ? 2 : (int)severity;
+    }
+
+    /// <summary>#478 — a canonical worst StatusCode for an alarm's last-observed quality bucket, used by
+    /// the operator-command + shelving-timer emission paths (which don't re-read inputs) so an ack /
+    /// shelve while an input is Bad still carries Bad rather than resetting the condition to Good.</summary>
+    private uint LastWorstStatus(string alarmId)
+        => (_lastQualityBucketByAlarmId.TryGetValue(alarmId, out var bucket) ? bucket : 0) switch
+        {
+            2 => 0x80000000u, // Bad
+            1 => 0x40000000u, // Uncertain
+            _ => 0u,          // Good
+        };
+
    /// <summary>
    ///     Invoke the <see cref="OnEvent"/> handler for a built emission. Must be
    ///     called OUTSIDE <c>_evalGate</c>: a slow subscriber would otherwise
@@ -708,7 +824,7 @@ public sealed class ScriptedAlarmEngine : IDisposable
                        _alarms[id] = state with { Condition = result.State };
                        if (result.Emission != EmissionKind.None)
                        {
-                            var evt = BuildEmission(state, result.State, result.Emission);
+                            var evt = BuildEmission(state, result.State, result.Emission, LastWorstStatus(id));
                            if (evt is not null) pending.Add(evt);
                        }
                    }
@@ -780,6 +896,7 @@ public sealed class ScriptedAlarmEngine : IDisposable
        _alarms.Clear();
        _alarmsReferencing.Clear();
        _scratchByAlarmId.Clear();
+        _lastQualityBucketByAlarmId.Clear();
        // Dispose every compiled-predicate ALC so the engine's shutdown actually
        // releases the emitted assemblies. The drain above ensures no evaluator is
        // mid-call; CompiledScriptCache.Dispose internally guards against use-after-
@@ -851,7 +968,11 @@ public sealed record ScriptedAlarmEvent(
    EmissionKind Emission,
    DateTime TimestampUtc,
    string? Comment = null,
-    bool HistorizeToAveva = true);
+    bool HistorizeToAveva = true,
+    // #478 — the worst OPC UA StatusCode across the alarm's input tags at evaluation time. A raw uint
+    // (Core.ScriptedAlarms does not reference Commons/OpcUaQuality); the host maps it to OpcUaQuality by
+    // the top-2 severity bits. Default 0u == Good keeps every existing constructor call unchanged.
+    uint WorstInputStatusCode = 0u);

 /// <summary>
 ///     Upstream source abstraction — intentionally identical shape to the virtual-tag
@@ -81,6 +81,11 @@ public sealed class ScriptedAlarmSource : IAlarmSource, IDisposable
    {
        if (_disposed) return;

+        // #478 — QualityChanged is a source-quality annotation, not a Part 9 state change. It is delivered
+        // out of band via the dedicated WriteAlarmQuality node path; surfacing it here would fabricate a
+        // phantom AlarmEventArgs that materializes / historizes a condition. Swallow it.
+        if (evt.Emission == EmissionKind.QualityChanged) return;
+
        foreach (var sub in _subscriptions.Values)
        {
            if (!Matches(sub, evt)) continue;
@@ -0,0 +1,473 @@
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Logging.Abstractions;
+using Serilog;
+using ZB.MOM.WW.OtOpcUa.Commons.Engines;
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+using ZB.MOM.WW.OtOpcUa.Core.Scripting;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Calculation;
+
+/// <summary>
+///     The <c>Calculation</c> pseudo-driver. Its tags are ordinary raw tags whose value is <b>computed</b>
+///     by a C# script over other tags' live values — there is no backend, no endpoint, no discovery, no
+///     writes. It implements:
+///     <list type="bullet">
+///       <item><see cref="IDriver"/> — lifecycle + always-Connected health.</item>
+///       <item><see cref="IDependencyConsumer"/> — the host feeds it the other tags' live values.</item>
+///       <item><see cref="ISubscribable"/> — computed values flow out via <see cref="OnDataChange"/>
+///       exactly like any driver, so the ordinary node fan-out + the mux re-entry (calc-of-calc) apply.</item>
+///       <item><see cref="IReadable"/> — on-demand read returns the last computed snapshot
+///       (<c>BadWaitingForInitialData</c> before the first evaluation).</item>
+///     </list>
+///
+///     <para>
+///         <b>Triggers.</b> A tag re-evaluates on any of its declared dependencies changing (change-trigger,
+///         gated exactly like <c>VirtualTagActor</c>: nothing publishes until every declared dep has arrived
+///         at least once, and equal results are deduped) and/or on a timer (one timer per interval group).
+///     </para>
+///     <para>
+///         <b>Error semantics (mini-design §6).</b> An evaluator <c>Failure</c> publishes <b>Bad</b> quality
+///         carrying the last-known value, once per Good→Bad transition and only after all deps have arrived,
+///         and emits a <c>ScriptLogEntry</c> on the <c>script-logs</c> topic (via the injected
+///         <see cref="ScriptRootLogger"/>'s <c>ScriptLogTopicSink</c>). Recovery to Good is force-published.
+///         A historized Bad records <c>BadInternalError</c>.
+///     </para>
+/// </summary>
+public sealed class CalculationDriver : IDriver, IDependencyConsumer, ISubscribable, IReadable, IDisposable
+{
+    // OPC UA status codes surfaced by the calc driver.
+    private const uint StatusGood = 0u;
+    private const uint StatusBadWaitingForInitialData = 0x80320000u;
+    private const uint StatusBadInternalError = 0x80020000u;
+
+    private readonly string _driverInstanceId;
+    private readonly CalculationDriverOptions _options;
+    private readonly ILogger<CalculationDriver> _logger;
+    private readonly ScriptRootLogger _scriptRoot;
+    private readonly CalculationEvaluator _evaluator;
+
+    // Authored calc tags, keyed by RawPath (identity + evaluation id). Built at construction so
+    // DependencyRefs is available BEFORE InitializeAsync (the host reads it when spawning the mux-adapter),
+    // and REBUILT on every ReinitializeAsync (an in-place ApplyDelta re-binds an edited calc-tag set).
+    private readonly Dictionary<string, CalculationTagDefinition> _tagsByRawPath = new(StringComparer.Ordinal);
+
+    // rawPath (a dependency) → the calc tags that read it AND are change-triggered. Drives OnDependencyValue.
+    private readonly Dictionary<string, List<string>> _changeDependents = new(StringComparer.Ordinal);
+
+    // Union of every tag's declared dependency refs — the interest set the host registers on the mux.
+    // Reassigned by RebuildTagTable so a redeploy that adds/removes dependencies re-registers on the mux.
+    private IReadOnlyCollection<string> _dependencyRefs = Array.Empty<string>();
+
+    // Live evaluation state. Guarded by _lock: OnDependencyValue (actor thread) and timer ticks
+    // (pool threads) can both drive an evaluation, so all state mutation is serialized.
+    private readonly object _lock = new();
+    private readonly Dictionary<string, object?> _depValues = new(StringComparer.Ordinal);
+    private readonly HashSet<string> _arrivedDeps = new(StringComparer.Ordinal);
+    private readonly Dictionary<string, TagState> _stateByRawPath = new(StringComparer.Ordinal);
+
+    private CalculationTimerScheduler? _timers;
+    private volatile bool _running;
+    private DateTime? _lastComputeUtc;
+    private bool _disposed;
+
+    /// <summary>Occurs when a calc tag's computed value changes (or transitions Good↔Bad).</summary>
+    public event EventHandler<DataChangeEventArgs>? OnDataChange;
+
+    /// <summary>Initializes a new <see cref="CalculationDriver"/>.</summary>
+    /// <param name="options">Bound options carrying the authored raw calc tags.</param>
+    /// <param name="driverInstanceId">Stable logical id of this driver instance.</param>
+    /// <param name="scriptRoot">Root script logger — user <c>ctx.Logger</c> output + failure entries fan out
+    /// to the <c>script-logs</c> topic through its <c>ScriptLogTopicSink</c>. When null a no-op logger is used.</param>
+    /// <param name="logger">Host-side diagnostics logger; defaults to the null logger.</param>
+    public CalculationDriver(
+        CalculationDriverOptions options,
+        string driverInstanceId,
+        ScriptRootLogger? scriptRoot = null,
+        ILogger<CalculationDriver>? logger = null)
+    {
+        ArgumentNullException.ThrowIfNull(options);
+        ArgumentException.ThrowIfNullOrWhiteSpace(driverInstanceId);
+        _options = options;
+        _driverInstanceId = driverInstanceId;
+        _logger = logger ?? NullLogger<CalculationDriver>.Instance;
+        _scriptRoot = scriptRoot ?? new ScriptRootLogger(new LoggerConfiguration().CreateLogger());
+        _evaluator = new CalculationEvaluator(
+            _logger is ILogger<CalculationEvaluator> el ? el : NullLogger<CalculationEvaluator>.Instance,
+            _scriptRoot,
+            _options.RunTimeout);
+
+        RebuildTagTable(_options);
+    }
+
+    /// <summary>
+    ///     (Re)build the authored tag table (<see cref="_tagsByRawPath"/>), the change-trigger fan-out
+    ///     (<see cref="_changeDependents"/>), the dependency-ref interest set (<see cref="_dependencyRefs"/>),
+    ///     and the per-tag state map (<see cref="_stateByRawPath"/>) from <paramref name="config"/>. Called
+    ///     once at construction AND on every <see cref="ReinitializeAsync"/> so an in-place ApplyDelta — a
+    ///     calc-tag add/remove/edit, or a script-source edit — actually takes effect. Extracted so the ctor
+    ///     and reinit paths share ONE construction routine and cannot drift.
+    ///     <para>Per-tag <see cref="TagState"/> is preserved for a tag that survives the edit (cheap last-known
+    ///     value carry-over); a brand-new tag starts fresh; a removed tag's state is dropped. MUST be called
+    ///     under <see cref="_lock"/> when invoked post-construction (the ctor runs single-threaded).</para>
+    /// </summary>
+    /// <param name="config">The (new) bound options carrying the authored raw calc tags.</param>
+    private void RebuildTagTable(CalculationDriverOptions config)
+    {
+        _tagsByRawPath.Clear();
+        _changeDependents.Clear();
+        // Retain surviving tags' state; anything not re-authored is dropped when we swap this in below.
+        var retainedState = new Dictionary<string, TagState>(StringComparer.Ordinal);
+
+        foreach (var entry in config.RawTags)
+        {
+            if (!CalculationTagDefinition.TryFromTagConfig(entry.TagConfig, entry.RawPath, out var def))
+            {
+                _logger.LogWarning(
+                    "Calculation {Driver}: raw tag {RawPath} has no scriptId; skipping (not a calc tag)",
+                    _driverInstanceId, entry.RawPath);
+                continue;
+            }
+            if (string.IsNullOrWhiteSpace(def.ScriptSource))
+            {
+                _logger.LogWarning(
+                    "Calculation {Driver}: calc tag {RawPath} (script {Script}) has no resolved scriptSource; " +
+                    "it will not compute until the deploy artifact injects the script source",
+                    _driverInstanceId, entry.RawPath, def.ScriptId);
+            }
+            _tagsByRawPath[entry.RawPath] = def;
+            // Carry the last-known state forward for a surviving tag; a brand-new tag starts fresh.
+            retainedState[entry.RawPath] =
+                _stateByRawPath.TryGetValue(entry.RawPath, out var prior) ? prior : new TagState();
+            if (def.ChangeTriggered)
+            {
+                foreach (var dep in def.DependencyRefs)
+                {
+                    if (!_changeDependents.TryGetValue(dep, out var list))
+                        _changeDependents[dep] = list = new List<string>();
+                    if (!list.Contains(entry.RawPath, StringComparer.Ordinal)) list.Add(entry.RawPath);
+                }
+            }
+        }
+
+        // Swap in the retained/new state map — a removed tag's state is dropped so it stops publishing.
+        _stateByRawPath.Clear();
+        foreach (var (rawPath, state) in retainedState) _stateByRawPath[rawPath] = state;
+
+        _dependencyRefs = _tagsByRawPath.Values
+            .SelectMany(t => t.DependencyRefs)
+            .Distinct(StringComparer.Ordinal)
+            .ToArray();
+    }
+
+    // Reinit config-bind options — mirrors the factory's bind (case-insensitive, enum-string, trailing-comma
+    // tolerant) so an ApplyDelta payload re-binds identically to the spawn payload.
+    private static readonly JsonSerializerOptions ReinitJsonOptions = new()
+    {
+        PropertyNameCaseInsensitive = true,
+        ReadCommentHandling = JsonCommentHandling.Skip,
+        AllowTrailingCommas = true,
+        Converters = { new JsonStringEnumConverter() },
+    };
+
+    /// <summary>Re-bind the authored raw calc tags from a new merged DriverConfig JSON (the ApplyDelta
+    /// payload). The ctor-fixed <see cref="CalculationEvaluator"/> timeout is kept — <c>RunTimeout</c> is bound
+    /// at spawn (a change to it is out of this in-place path's scope). A parse failure logs and keeps the
+    /// current tags so a malformed delta can never blank the driver.</summary>
+    private CalculationDriverOptions ParseOptions(string driverConfigJson)
+    {
+        if (!string.IsNullOrWhiteSpace(driverConfigJson))
+        {
+            try
+            {
+                var dto = JsonSerializer.Deserialize<ReinitConfigDto>(driverConfigJson, ReinitJsonOptions);
+                if (dto is not null)
+                {
+                    return new CalculationDriverOptions
+                    {
+                        RawTags = dto.RawTags is { Count: > 0 } ? [.. dto.RawTags] : [],
+                        RunTimeout = _options.RunTimeout,
+                    };
+                }
+            }
+            catch (JsonException ex)
+            {
+                _logger.LogWarning(ex,
+                    "Calculation {Driver}: reinit config parse failed; keeping the current tag table",
+                    _driverInstanceId);
+            }
+        }
+        return new CalculationDriverOptions { RawTags = _options.RawTags, RunTimeout = _options.RunTimeout };
+    }
+
+    /// <summary>Minimal reinit-bind DTO — the calc driver has no backend config, only the injected raw tags
+    /// (+ an optional eval-timeout, ignored on reinit since the evaluator is ctor-fixed). Mirrors the factory's
+    /// <c>CalculationDriverConfigDto</c>.</summary>
+    private sealed class ReinitConfigDto
+    {
+        public List<RawTagEntry>? RawTags { get; init; }
+        public int? RunTimeoutMs { get; init; }
+    }
+
+    // ---- IDriver ----
+
+    /// <inheritdoc />
+    public string DriverInstanceId => _driverInstanceId;
+
+    /// <inheritdoc />
+    public string DriverType => DriverTypeNames.Calculation;
+
+    /// <inheritdoc />
+    public Task InitializeAsync(string driverConfigJson, CancellationToken cancellationToken)
+    {
+        _running = true;
+        StartTimers();
+        _logger.LogInformation(
+            "Calculation {Driver}: initialized with {TagCount} calc tag(s), {DepCount} distinct dependency ref(s)",
+            _driverInstanceId, _tagsByRawPath.Count, _dependencyRefs.Count);
+        return Task.CompletedTask;
+    }
+
+    /// <inheritdoc />
+    public Task ReinitializeAsync(string driverConfigJson, CancellationToken cancellationToken)
+    {
+        // A calc-tag add/remove/edit — or a script edit that changes the injected scriptSource — changes the
+        // merged DriverConfig, which DriverSpawnPlanner routes to an in-place ApplyDelta → THIS call (a
+        // respawn fires only on a DriverType/ResilienceConfig change). So the authored tag table is NOT
+        // fixed at construction: we re-bind the new config and REBUILD the tag table + dependency-ref set
+        // here. Without this, added tags never compute, removed tags keep publishing, and edited scripts
+        // serve stale results (deploy reports success but nothing changed). After the rebuild _dependencyRefs
+        // reflects the new authored tags, and the host re-registers the mux interest post-reinit (the
+        // DriverInstanceActor.DeltaApplied → DriverHostActor path, sequenced AFTER this completes).
+        StopTimers();
+        var newOptions = ParseOptions(driverConfigJson);
+        lock (_lock)
+        {
+            RebuildTagTable(newOptions);
+        }
+        // Drop compiled scripts (IScriptCacheOwner contract — stops collectible ALCs accreting AND forces a
+        // recompile from each tag's NEW ScriptSource) + re-arm timers off the rebuilt tag set.
+        _evaluator.ClearCompiledScripts();
+        _running = true;
+        StartTimers();
+        return Task.CompletedTask;
+    }
+
+    /// <inheritdoc />
+    public Task ShutdownAsync(CancellationToken cancellationToken)
+    {
+        _running = false;
+        StopTimers();
+        return Task.CompletedTask;
+    }
+
+    /// <inheritdoc />
+    public DriverHealth GetHealth() => new(DriverState.Healthy, _lastComputeUtc, null);
+
+    /// <inheritdoc />
+    public long GetMemoryFootprint() => 0;
+
+    /// <inheritdoc />
+    public Task FlushOptionalCachesAsync(CancellationToken cancellationToken)
+    {
+        // The compile cache is the only optional cache; dropping it is safe (recompiled on next eval).
+        _evaluator.ClearCompiledScripts();
+        return Task.CompletedTask;
+    }
+
+    // ---- IDependencyConsumer ----
+
+    /// <inheritdoc />
+    public IReadOnlyCollection<string> DependencyRefs => _dependencyRefs;
+
+    /// <inheritdoc />
+    public void OnDependencyValue(string rawPath, object? value, uint statusCode, DateTime timestampUtc)
+    {
+        if (!_running) return;
+        List<string>? dependents;
+        lock (_lock)
+        {
+            _depValues[rawPath] = value;
+            _arrivedDeps.Add(rawPath);
+            if (!_changeDependents.TryGetValue(rawPath, out dependents) || dependents.Count == 0) return;
+            // Evaluate each change-triggered dependent inline under the lock (the compile cache makes this
+            // a bounded method invocation — the same "fast enough to run inline" contract as the VT evaluator).
+            foreach (var calcRawPath in dependents)
+                EvaluateTag(calcRawPath, timestampUtc);
+        }
+    }
+
+    // ---- ISubscribable ----
+
+    /// <inheritdoc />
+    public Task<ISubscriptionHandle> SubscribeAsync(
+        IReadOnlyList<string> fullReferences, TimeSpan publishingInterval, CancellationToken cancellationToken)
+    {
+        ArgumentNullException.ThrowIfNull(fullReferences);
+        var handle = new CalculationSubscriptionHandle($"calc-{Guid.NewGuid():N}");
+        // Initial-data callback (OPC UA convention): surface the current snapshot for each subscribed calc
+        // tag so a freshly-materialised node shows BadWaitingForInitialData until its first evaluation lands.
+        foreach (var reference in fullReferences)
+        {
+            var snapshot = ReadOne(reference);
+            OnDataChange?.Invoke(this, new DataChangeEventArgs(handle, reference, snapshot));
+        }
+        return Task.FromResult<ISubscriptionHandle>(handle);
+    }
+
+    /// <inheritdoc />
+    public Task UnsubscribeAsync(ISubscriptionHandle handle, CancellationToken cancellationToken)
+        => Task.CompletedTask;
+
+    // ---- IReadable ----
+
+    /// <inheritdoc />
+    public Task<IReadOnlyList<DataValueSnapshot>> ReadAsync(
+        IReadOnlyList<string> fullReferences, CancellationToken cancellationToken)
+    {
+        ArgumentNullException.ThrowIfNull(fullReferences);
+        var results = new DataValueSnapshot[fullReferences.Count];
+        for (var i = 0; i < fullReferences.Count; i++)
+            results[i] = ReadOne(fullReferences[i]);
+        return Task.FromResult<IReadOnlyList<DataValueSnapshot>>(results);
+    }
+
+    private DataValueSnapshot ReadOne(string reference)
+    {
+        var now = DateTime.UtcNow;
+        lock (_lock)
+        {
+            if (!_stateByRawPath.TryGetValue(reference, out var st) || !st.HasValue)
+                return new DataValueSnapshot(null, StatusBadWaitingForInitialData, null, now);
+            var status = st.LastPublishedBad ? StatusBadInternalError : StatusGood;
+            return new DataValueSnapshot(st.LastValue, status, st.LastTimestampUtc, st.LastTimestampUtc);
+        }
+    }
+
+    // ---- evaluation ----
+
+    /// <summary>Timer-trigger entry point — evaluates a single calc tag. Guards the lock itself (called
+    /// from a pool thread, unlike the change path which is already under the lock).</summary>
+    private void EvaluateTagLocked(string rawPath)
+    {
+        if (!_running) return;
+        lock (_lock) EvaluateTag(rawPath, DateTime.UtcNow);
+    }
+
+    /// <summary>Evaluate one calc tag and publish the outcome. MUST be called under <see cref="_lock"/>.</summary>
+    private void EvaluateTag(string rawPath, DateTime timestampUtc)
+    {
+        if (!_tagsByRawPath.TryGetValue(rawPath, out var def)) return;
+        if (string.IsNullOrWhiteSpace(def.ScriptSource)) return; // unresolved script — never computes (logged at init)
+
+        var st = _stateByRawPath[rawPath];
+
+        // Change-gate (mini-design §4): publish nothing until every declared dep has arrived at least once.
+        var allArrived = def.DependencyRefs.All(_arrivedDeps.Contains);
+
+        // Build the per-tag dependency snapshot (only its declared reads, current values).
+        var deps = new Dictionary<string, object?>(StringComparer.Ordinal);
+        foreach (var dep in def.DependencyRefs)
+            if (_depValues.TryGetValue(dep, out var v)) deps[dep] = v;
+
+        var result = _evaluator.Evaluate(rawPath, def.ScriptSource, deps);
+
+        if (!result.Success)
+        {
+            OnEvaluationFailed(def, st, result.Reason ?? "evaluator failure", allArrived, timestampUtc);
+            return;
+        }
+
+        if (!allArrived) return; // change-trigger warm-up: hold until inputs are ready
+
+        // Value dedup — but bypass it while recovering from Bad so a recovery whose value equals the
+        // pre-failure value still republishes Good (otherwise the node would stay Bad forever).
+        if (!st.LastPublishedBad && st.HasValue && Equals(st.LastValue, result.Value))
+            return;
+
+        st.HasValue = true;
+        st.LastValue = result.Value;
+        st.LastPublishedBad = false;
+        st.LastTimestampUtc = timestampUtc;
+        _lastComputeUtc = DateTime.UtcNow;
+        Publish(rawPath, result.Value, StatusGood, timestampUtc);
+    }
+
+    /// <summary>Failure tail (mirrors <c>VirtualTagActor</c> 02/S13): always emits the per-failure
+    /// script-log; additionally publishes a Bad snapshot — carrying the last-known value — once per
+    /// Good→Bad transition and only after every declared dependency has arrived.</summary>
+    private void OnEvaluationFailed(
+        CalculationTagDefinition def, TagState st, string reason, bool allArrived, DateTime timestampUtc)
+    {
+        PublishScriptLog(def, reason);
+        if (st.LastPublishedBad || !allArrived) return;
+
+        st.LastPublishedBad = true;
+        st.LastTimestampUtc = timestampUtc;
+        // Carry the last-known value (null if none) with Bad quality.
+        Publish(def.RawPath, st.HasValue ? st.LastValue : null, StatusBadInternalError, timestampUtc);
+    }
+
+    private void Publish(string rawPath, object? value, uint statusCode, DateTime timestampUtc)
+    {
+        var snapshot = new DataValueSnapshot(value, statusCode, timestampUtc, timestampUtc);
+        // Fired under _lock — the subscriber (DriverInstanceActor) marshals the event to its own thread,
+        // so there is no re-entrant call back into this driver.
+        OnDataChange?.Invoke(this, new DataChangeEventArgs(SharedHandle, rawPath, snapshot));
+    }
+
+    private void PublishScriptLog(CalculationTagDefinition def, string reason)
+    {
+        // Route through the script logger bound with ScriptId + the calc tag's RawPath (in the VirtualTagId
+        // slot the Script-log page attributes on). The ScriptRootLogger's ScriptLogTopicSink converts this
+        // Warning event into a ScriptLogEntry on the script-logs DPS topic — the driver needs no Akka access.
+        _scriptRoot.Logger
+            .ForContext(ScriptLoggerFactory.ScriptIdProperty, def.ScriptId)
+            .ForContext(ScriptLoggerFactory.VirtualTagIdProperty, def.RawPath)
+            .Warning("{Reason}", reason);
+    }
+
+    private void StartTimers()
+    {
+        var timed = _tagsByRawPath.Values.Where(t => t.TimerInterval is not null).ToArray();
+        if (timed.Length == 0) return;
+        _timers = new CalculationTimerScheduler(EvaluateTagLocked, _logger);
+        _timers.Start(timed);
+    }
+
+    private void StopTimers()
+    {
+        _timers?.Dispose();
+        _timers = null;
+    }
+
+    /// <summary>Test/diagnostic accessor: number of timer ticks skipped for in-flight groups.</summary>
+    internal long TimerSkippedTickCount => _timers?.SkippedTickCount ?? 0;
+
+    // A single shared handle for host-pushed publishes (change + timer). SubscribeAsync mints its own
+    // per-call handle for the initial-data callback; steady-state publishes reuse this so OnDataChange
+    // always carries a non-null handle.
+    private static readonly CalculationSubscriptionHandle SharedHandle = new("calc-shared");
+
+    /// <inheritdoc />
+    public void Dispose()
+    {
+        if (_disposed) return;
+        _disposed = true;
+        _running = false;
+        StopTimers();
+        _evaluator.Dispose();
+    }
+
+    /// <summary>Per-tag published state (guarded by <see cref="_lock"/>).</summary>
+    private sealed class TagState
+    {
+        public bool HasValue;
+        public object? LastValue;
+        public bool LastPublishedBad;
+        public DateTime LastTimestampUtc;
+    }
+
+    private sealed record CalculationSubscriptionHandle(string DiagnosticId) : ISubscriptionHandle;
+}
@@ -0,0 +1,96 @@
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using Microsoft.Extensions.Logging;
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+using ZB.MOM.WW.OtOpcUa.Core.Hosting;
+using ZB.MOM.WW.OtOpcUa.Core.Scripting;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Calculation;
+
+/// <summary>
+///     Static factory registration helper for <see cref="CalculationDriver"/>. The Server's
+///     <c>DriverFactoryBootstrap</c> calls <see cref="Register"/> once at startup; the bootstrapper then
+///     materialises <c>Calculation</c> DriverInstance rows into live driver instances. Mirrors
+///     <c>ModbusDriverFactoryExtensions</c>, with the addition of a <see cref="ScriptRootLogger"/> so a
+///     script failure fans out onto the <c>script-logs</c> topic (via the root logger's
+///     <c>ScriptLogTopicSink</c>) — the calc driver has no Akka access of its own.
+/// </summary>
+public static class CalculationDriverFactoryExtensions
+{
+    /// <summary>The <c>DriverInstance.DriverType</c> string this factory registers under.</summary>
+    public const string DriverTypeName = "Calculation";
+
+    private static readonly JsonSerializerOptions JsonOptions = new()
+    {
+        PropertyNameCaseInsensitive = true,
+        ReadCommentHandling = JsonCommentHandling.Skip,
+        AllowTrailingCommas = true,
+        Converters = { new JsonStringEnumConverter() },
+    };
+
+    /// <summary>
+    ///     Register the Calculation factory with the driver registry. The optional
+    ///     <paramref name="loggerFactory"/> + <paramref name="scriptRoot"/> are captured at registration
+    ///     time; both may be null (the guard test invokes <c>Register(registry)</c> reflectively with the
+    ///     trailing parameters defaulted), in which case the driver runs with the null logger + a no-op
+    ///     script-logger.
+    /// </summary>
+    /// <param name="registry">The driver factory registry to register with.</param>
+    /// <param name="loggerFactory">Optional logger factory for per-instance diagnostics loggers.</param>
+    /// <param name="scriptRoot">Optional root script logger (fans failure entries onto the <c>script-logs</c> topic).</param>
+    public static void Register(
+        DriverFactoryRegistry registry,
+        ILoggerFactory? loggerFactory = null,
+        ScriptRootLogger? scriptRoot = null)
+    {
+        ArgumentNullException.ThrowIfNull(registry);
+        registry.Register(DriverTypeName, (id, json) => CreateInstance(id, json, loggerFactory, scriptRoot));
+    }
+
+    /// <summary>Public overload for the Server-side bootstrapper + test consumers.</summary>
+    /// <param name="driverInstanceId">The unique identifier for the driver instance.</param>
+    /// <param name="driverConfigJson">The merged driver config JSON (carries the <c>RawTags</c> array).</param>
+    /// <returns>The constructed <see cref="CalculationDriver"/>.</returns>
+    public static CalculationDriver CreateInstance(string driverInstanceId, string driverConfigJson)
+        => CreateInstance(driverInstanceId, driverConfigJson, loggerFactory: null, scriptRoot: null);
+
+    /// <summary>Logger/script-logger-aware overload — used by <see cref="Register"/>'s closure via DI.</summary>
+    /// <param name="driverInstanceId">The unique identifier for the driver instance.</param>
+    /// <param name="driverConfigJson">The merged driver config JSON (carries the <c>RawTags</c> array).</param>
+    /// <param name="loggerFactory">Optional logger factory for per-instance diagnostics loggers.</param>
+    /// <param name="scriptRoot">Optional root script logger for failure fan-out.</param>
+    /// <returns>The constructed <see cref="CalculationDriver"/>.</returns>
+    public static CalculationDriver CreateInstance(
+        string driverInstanceId, string driverConfigJson,
+        ILoggerFactory? loggerFactory, ScriptRootLogger? scriptRoot)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(driverInstanceId);
+        ArgumentException.ThrowIfNullOrWhiteSpace(driverConfigJson);
+
+        var dto = JsonSerializer.Deserialize<CalculationDriverConfigDto>(driverConfigJson, JsonOptions)
+            ?? throw new InvalidOperationException(
+                $"Calculation driver config for '{driverInstanceId}' deserialised to null");
+
+        var options = new CalculationDriverOptions
+        {
+            RawTags = dto.RawTags is { Count: > 0 } ? [.. dto.RawTags] : [],
+            RunTimeout = dto.RunTimeoutMs is { } ms && ms > 0
+                ? TimeSpan.FromMilliseconds(ms) : TimeSpan.FromSeconds(2),
+        };
+
+        return new CalculationDriver(
+            options, driverInstanceId, scriptRoot,
+            logger: loggerFactory?.CreateLogger<CalculationDriver>());
+    }
+
+    /// <summary>The merged-config DTO the calc factory binds from. The Calculation driver has no
+    /// backend/endpoint config — only the injected raw tags (+ an optional evaluation-timeout override).</summary>
+    internal sealed class CalculationDriverConfigDto
+    {
+        /// <summary>The driver's authored raw calc tags (RawPath + TagConfig blob + WriteIdempotent + DeviceName).</summary>
+        public List<RawTagEntry>? RawTags { get; init; }
+
+        /// <summary>Optional per-script evaluation wall-clock budget override, in milliseconds (default 2000).</summary>
+        public int? RunTimeoutMs { get; init; }
+    }
+}
@@ -0,0 +1,20 @@
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Calculation;
+
+/// <summary>
+///     Bound options for a <see cref="CalculationDriver"/> instance. The Calculation pseudo-driver has
+///     no backend/endpoint config — its only input is the authored raw calc tags the deploy artifact
+///     injects as the <see cref="RawTags"/> list (each carrying the tag's <c>scriptId</c> + resolved
+///     <c>scriptSource</c> + trigger config inside its <see cref="RawTagEntry.TagConfig"/> blob).
+/// </summary>
+public sealed class CalculationDriverOptions
+{
+    /// <summary>The driver's authored raw calc tags (RawPath + TagConfig blob + WriteIdempotent), from
+    /// the deploy artifact. Each is mapped to a <see cref="CalculationTagDefinition"/> at construction.</summary>
+    public IReadOnlyList<RawTagEntry> RawTags { get; init; } = Array.Empty<RawTagEntry>();
+
+    /// <summary>Per-script wall-clock evaluation budget handed to the <see cref="CalculationEvaluator"/>.
+    /// Defaults to 2 seconds (parity with the VirtualTag evaluator).</summary>
+    public TimeSpan RunTimeout { get; init; } = TimeSpan.FromSeconds(2);
+}
@@ -0,0 +1,45 @@
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Calculation;
+
+/// <summary>
+///     Test-connect probe for the <c>Calculation</c> pseudo-driver. There is no backend to connect to —
+///     the driver computes tags from other tags' values — so the probe just confirms the driver config
+///     parses (mini-design §7). Per-script compile verification belongs to the editor diagnostics + the
+///     tag editor's inline panel, not the probe (which receives only the driver config). Never throws;
+///     returns Ok with negligible latency.
+/// </summary>
+public sealed class CalculationDriverProbe : IDriverProbe
+{
+    private static readonly JsonSerializerOptions Opts = new()
+    {
+        PropertyNameCaseInsensitive = true,
+        UnmappedMemberHandling = JsonUnmappedMemberHandling.Skip,
+        Converters = { new JsonStringEnumConverter() },
+    };
+
+    /// <inheritdoc />
+    public string DriverType => CalculationDriverFactoryExtensions.DriverTypeName;
+
+    /// <inheritdoc />
+    public Task<DriverProbeResult> ProbeAsync(string configJson, TimeSpan timeout, CancellationToken ct)
+    {
+        if (string.IsNullOrWhiteSpace(configJson))
+            return Task.FromResult(new DriverProbeResult(false, "Config JSON is empty.", null));
+
+        try
+        {
+            // Parse-only: a Calculation driver's config is well-formed as long as it deserialises to an
+            // object (the RawTags array is optional — a driver with no calc tags is still valid).
+            _ = JsonSerializer.Deserialize<CalculationDriverFactoryExtensions.CalculationDriverConfigDto>(configJson, Opts);
+        }
+        catch (Exception ex)
+        {
+            return Task.FromResult(new DriverProbeResult(false, $"Config JSON is invalid: {ex.Message}", null));
+        }
+
+        return Task.FromResult(new DriverProbeResult(true, null, TimeSpan.Zero));
+    }
+}
@@ -0,0 +1,193 @@
+using Microsoft.Extensions.Logging;
+using ZB.MOM.WW.OtOpcUa.Commons.Engines;
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+using ZB.MOM.WW.OtOpcUa.Core.Scripting;
+using ZB.MOM.WW.OtOpcUa.Core.VirtualTags;
+using SerilogLogger = Serilog.ILogger;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Calculation;
+
+/// <summary>
+/// T0-4 — the Calculation driver's script evaluator. A calc tag is a raw tag whose value is
+/// produced by a C# script over other tags' live values. This evaluator is a deliberate mirror of
+/// the VirtualTag <c>RoslynVirtualTagEvaluator</c>: it compiles each unique source once via
+/// <see cref="ScriptEvaluator{TContext, TResult}"/> (the Roslyn-backed sandbox), caches the
+/// resulting evaluator keyed by source in a <see cref="CompiledScriptCache{TContext, TResult}"/>,
+/// and runs steady-state evaluations as in-process method invocations against the dependency
+/// dictionary — fast enough to run inline on the driver's dispatch. It reuses
+/// <see cref="VirtualTagContext"/> verbatim so the Monaco editor, sandbox, and diagnostics pipeline
+/// apply to calc scripts with no divergence.
+///
+/// <para>
+///     <b>Single-tag mode.</b> A calc tag produces exactly one output value — its own — so cross-tag
+///     <c>ctx.SetVirtualTag</c> writes are dropped (and logged at Debug). Fan-out between tags is owned
+///     by the host's <c>DependencyMuxActor</c> (calc-of-calc chains re-enter the mux), never by the
+///     eval engine, exactly as in the VirtualTag adapter.
+/// </para>
+/// <para>
+///     <b>Error surfacing (for WP7).</b> This evaluator never throws for script faults: compile error,
+///     sandbox violation, runtime throw, and timeout all return <see cref="VirtualTagEvalResult.Failure"/>
+///     with a descriptive <c>Reason</c>. A successful run returns <see cref="VirtualTagEvalResult.Ok"/>
+///     carrying the computed value (which may be null). WP7's <c>CalculationDriver</c> maps a
+///     <c>Failure</c> to Bad quality + a <c>ScriptLogEntry</c> and an <c>Ok</c> to the published value.
+/// </para>
+/// <para>
+///     <b>Cache management.</b> Implements <see cref="IScriptCacheOwner"/> so WP7 can drop compiled
+///     scripts at each deploy generation whose source set changed — mirroring the VirtualTag adapter's
+///     apply-boundary clear, which is what stops collectible <c>AssemblyLoadContext</c>s accreting across
+///     script edits.
+/// </para>
+/// </summary>
+public sealed class CalculationEvaluator : IScriptCacheOwner, IDisposable
+{
+    // Source-hash-keyed compile cache: Lazy single-compile (no double-compile race) and Clear()/Dispose()
+    // that dispose each evaluator's collectible AssemblyLoadContext. ClearCompiledScripts() — driven by the
+    // WP7 driver per deploy generation — is what stops ALCs accreting across script edits.
+    private readonly CompiledScriptCache<VirtualTagContext, object?> _cache = new();
+    private readonly ILogger<CalculationEvaluator> _logger;
+    private readonly SerilogLogger _scriptRoot;
+    private readonly TimeSpan _runTimeout;
+    private bool _disposed;
+
+    /// <summary>Initializes a new <see cref="CalculationEvaluator"/>.</summary>
+    /// <param name="logger">Logger for host-side compilation/execution diagnostics.</param>
+    /// <param name="scriptRoot">Root script logger; user <c>ctx.Logger.*</c> output flows through this to the Script-log page.</param>
+    /// <param name="runTimeout">Wall-clock budget per script run; defaults to 2 seconds (parity with the VT evaluator).</param>
+    public CalculationEvaluator(
+        ILogger<CalculationEvaluator> logger,
+        ScriptRootLogger scriptRoot,
+        TimeSpan? runTimeout = null)
+    {
+        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
+        _scriptRoot = (scriptRoot ?? throw new ArgumentNullException(nameof(scriptRoot))).Logger;
+        _runTimeout = runTimeout ?? TimeSpan.FromSeconds(2);
+    }
+
+    /// <summary>
+    ///     Evaluate <paramref name="scriptSource"/> for the calc tag <paramref name="calcTagId"/> against
+    ///     the snapshot in <paramref name="dependencies"/> (RawPath → last value). Never throws — script
+    ///     faults are reported via <see cref="VirtualTagEvalResult.Failure"/>; a successful run returns
+    ///     <see cref="VirtualTagEvalResult.Ok"/> carrying the single computed value.
+    /// </summary>
+    /// <param name="calcTagId">Identity of the calc tag (bound to the script log; in the live path equals the script id).</param>
+    /// <param name="scriptSource">The C# script source producing the tag's value.</param>
+    /// <param name="dependencies">Read-only snapshot of dependency values keyed by RawPath.</param>
+    public VirtualTagEvalResult Evaluate(string calcTagId, string scriptSource, IReadOnlyDictionary<string, object?> dependencies)
+    {
+        if (_disposed) return VirtualTagEvalResult.Failure("evaluator disposed");
+        if (string.IsNullOrWhiteSpace(scriptSource)) return VirtualTagEvalResult.Failure("empty expression");
+
+        // Passthrough fast-path: the mirror shape `return ctx.GetTag("X").Value;` needs no Roslyn.
+        // Semantics are byte-identical to the compiled mirror: a present dependency returns its value
+        // (Ok), an absent one makes GetTag yield a Bad snapshot whose .Value is null, so the script
+        // returns null — Ok(null) here too. Near-misses fall through to the compiled path.
+        if (PassthroughScript.TryMatch(scriptSource, out var passthroughRef))
+        {
+            return dependencies.TryGetValue(passthroughRef, out var ptValue)
+                ? VirtualTagEvalResult.Ok(ptValue)
+                : VirtualTagEvalResult.Ok(null);
+        }
+
+        var readCache = BuildReadCache(dependencies);
+        // Per-evaluation script logger: bind both ScriptId and CalcTagId (via the VirtualTagId slot, which
+        // the Script-log page attributes on) from the calc-tag id so each line is attributable.
+        var scriptLog = _scriptRoot
+            .ForContext(ScriptLoggerFactory.ScriptIdProperty, calcTagId)
+            .ForContext(ScriptLoggerFactory.VirtualTagIdProperty, calcTagId);
+        var context = new VirtualTagContext(
+            readCache,
+            // Single-tag mode: a calc tag has exactly one output (its own), so cross-tag writes are dropped.
+            setVirtualTag: (path, _) =>
+                _logger.LogDebug("Calculation {Id}: cross-tag write to {Path} dropped (single-tag evaluator)",
+                    calcTagId, path),
+            logger: scriptLog);
+
+        // Fetch + run inside a bounded loop so an ObjectDisposedException caused by a concurrent
+        // ClearCompiledScripts (which disposed the evaluator between GetOrCompile and the run's
+        // disposed guard) re-fetches and retries exactly once. The loop runs at most twice.
+        for (var attempt = 0; ; attempt++)
+        {
+            ScriptEvaluator<VirtualTagContext, object?> evaluator;
+            try
+            {
+                evaluator = _cache.GetOrCompile(scriptSource);
+            }
+            catch (CompilationErrorException ex)
+            {
+                _logger.LogWarning(ex, "Calculation {Id}: Roslyn compile failed", calcTagId);
+                return VirtualTagEvalResult.Failure($"compile error: {ex.Message}");
+            }
+            catch (ScriptSandboxViolationException ex)
+            {
+                _logger.LogWarning(ex, "Calculation {Id}: sandbox violation", calcTagId);
+                return VirtualTagEvalResult.Failure($"sandbox violation: {ex.Message}");
+            }
+            catch (ObjectDisposedException)
+            {
+                // Fetch-time disposal is a shutdown signal (the cache is tearing down), not the
+                // apply-boundary race — never retry.
+                return VirtualTagEvalResult.Failure("evaluator disposed");
+            }
+            catch (Exception ex)
+            {
+                _logger.LogWarning(ex, "Calculation {Id}: compile threw", calcTagId);
+                return VirtualTagEvalResult.Failure($"compile failure: {ex.Message}");
+            }
+
+            try
+            {
+                // Route through TimedScriptEvaluator (Task.Run + WaitAsync): a raw CancellationToken can't
+                // interrupt a CPU-bound/infinite-loop Roslyn script, so the timed wrapper is what bounds a
+                // runaway script to the wall-clock budget instead of wedging the driver's dispatch.
+                var timed = new TimedScriptEvaluator<VirtualTagContext, object?>(evaluator, _runTimeout);
+                var raw = timed.RunAsync(context).GetAwaiter().GetResult();
+                return VirtualTagEvalResult.Ok(raw);
+            }
+            catch (ScriptTimeoutException)
+            {
+                return VirtualTagEvalResult.Failure($"script timed out after {_runTimeout.TotalSeconds:F1}s");
+            }
+            catch (ObjectDisposedException) when (!_disposed && attempt == 0)
+            {
+                // A concurrent ClearCompiledScripts disposed the evaluator between our GetOrCompile and the
+                // run's disposed-guard. Re-fetch (recompiling the same source into the CURRENT generation)
+                // and retry once. A second disposal mid-retry falls through to the failure path below.
+                continue;
+            }
+            catch (ObjectDisposedException)
+            {
+                return VirtualTagEvalResult.Failure("evaluator disposed during evaluation");
+            }
+            catch (Exception ex)
+            {
+                _logger.LogWarning(ex, "Calculation {Id}: script execution threw", calcTagId);
+                return VirtualTagEvalResult.Failure($"script threw: {ex.Message}");
+            }
+        }
+    }
+
+    /// <inheritdoc />
+    public void ClearCompiledScripts() => _cache.Clear();
+
+    private static IReadOnlyDictionary<string, DataValueSnapshot> BuildReadCache(
+        IReadOnlyDictionary<string, object?> deps)
+    {
+        // VirtualTagContext.GetTag returns a DataValueSnapshot — wrap each raw dep value as Good-quality
+        // so the script's `(int)ctx.GetTag("a").Value` pattern works. Null values stay null.
+        var nowUtc = DateTime.UtcNow;
+        var cache = new Dictionary<string, DataValueSnapshot>(StringComparer.Ordinal);
+        foreach (var kv in deps)
+        {
+            cache[kv.Key] = new DataValueSnapshot(kv.Value, StatusCode: 0u, SourceTimestampUtc: nowUtc, ServerTimestampUtc: nowUtc);
+        }
+        return cache;
+    }
+
+    /// <summary>Disposes the evaluator, draining + disposing every cached compile's collectible ALC.</summary>
+    public void Dispose()
+    {
+        if (_disposed) return;
+        _disposed = true;
+        _cache.Dispose();
+    }
+}
@@ -0,0 +1,85 @@
+using System.Text.Json;
+using ZB.MOM.WW.OtOpcUa.Commons.Types;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Calculation;
+
+
+/// <summary>
+///     A single authored calc tag as the driver runs it: its <see cref="RawPath"/> identity, the script
+///     that computes it (<see cref="ScriptId"/> for attribution, <see cref="ScriptSource"/> for
+///     evaluation), its trigger config (<see cref="ChangeTriggered"/> / <see cref="TimerInterval"/>), and
+///     the static <see cref="DependencyRefs"/> extracted from the script's literal
+///     <c>ctx.GetTag("…")</c> reads.
+/// </summary>
+/// <param name="RawPath">The tag's cluster-scoped RawPath — its identity + the calc-tag id passed to the evaluator.</param>
+/// <param name="ScriptId">Logical FK to the shared <c>Script</c> entity — bound to the failure script-log for attribution.</param>
+/// <param name="ScriptSource">The resolved C# script source that produces the tag's value; empty when unresolved.</param>
+/// <param name="ChangeTriggered">Re-evaluate whenever a declared dependency changes.</param>
+/// <param name="TimerInterval">Optional periodic re-evaluation cadence; null ⇒ change-trigger only.</param>
+/// <param name="DependencyRefs">Distinct literal <c>ctx.GetTag</c> RawPaths this tag reads (first-seen order).</param>
+public sealed record CalculationTagDefinition(
+    string RawPath,
+    string ScriptId,
+    string ScriptSource,
+    bool ChangeTriggered,
+    TimeSpan? TimerInterval,
+    IReadOnlyList<string> DependencyRefs)
+{
+    /// <summary>
+    ///     Map a calc tag's <c>TagConfig</c> blob (<c>{ "scriptId", "scriptSource", "changeTriggered",
+    ///     "timerIntervalMs" }</c>) + its RawPath into a <see cref="CalculationTagDefinition"/>. Returns
+    ///     <see langword="false"/> (and leaves <paramref name="def"/> null) only when the blob has no
+    ///     <c>scriptId</c> — a tag with no identifiable script cannot be a calc tag. A present
+    ///     <c>scriptId</c> with an empty/absent <c>scriptSource</c> still maps (the driver logs it and the
+    ///     tag never computes). Never throws — malformed JSON yields a miss.
+    /// </summary>
+    /// <param name="tagConfig">The calc tag's schemaless <c>TagConfig</c> JSON.</param>
+    /// <param name="rawPath">The tag's RawPath identity.</param>
+    /// <param name="def">The mapped definition when this returns <see langword="true"/>.</param>
+    /// <returns><see langword="true"/> when a definition (with a scriptId) was mapped.</returns>
+    public static bool TryFromTagConfig(string tagConfig, string rawPath, out CalculationTagDefinition def)
+    {
+        def = null!;
+        if (string.IsNullOrWhiteSpace(tagConfig)) return false;
+
+        string? scriptId;
+        string scriptSource;
+        bool changeTriggered;
+        int? timerMs;
+        try
+        {
+            using var doc = JsonDocument.Parse(tagConfig);
+            var root = doc.RootElement;
+            if (root.ValueKind != JsonValueKind.Object) return false;
+
+            scriptId = root.TryGetProperty("scriptId", out var sidEl) && sidEl.ValueKind == JsonValueKind.String
+                ? sidEl.GetString() : null;
+            if (string.IsNullOrWhiteSpace(scriptId)) return false;
+
+            scriptSource = root.TryGetProperty("scriptSource", out var srcEl) && srcEl.ValueKind == JsonValueKind.String
+                ? srcEl.GetString() ?? string.Empty : string.Empty;
+
+            // changeTriggered defaults to true (mini-design §2) — only an explicit false disables it.
+            changeTriggered = !(root.TryGetProperty("changeTriggered", out var ctEl)
+                && ctEl.ValueKind == JsonValueKind.False);
+
+            timerMs = root.TryGetProperty("timerIntervalMs", out var tEl)
+                && tEl.ValueKind == JsonValueKind.Number && tEl.TryGetInt32(out var ms) && ms > 0
+                ? ms : null;
+        }
+        catch (JsonException)
+        {
+            return false;
+        }
+
+        var deps = EquipmentScriptPaths.ExtractDependencyRefs(scriptSource);
+        def = new CalculationTagDefinition(
+            RawPath: rawPath,
+            ScriptId: scriptId!,
+            ScriptSource: scriptSource,
+            ChangeTriggered: changeTriggered,
+            TimerInterval: timerMs is { } m ? TimeSpan.FromMilliseconds(m) : null,
+            DependencyRefs: deps);
+        return true;
+    }
+}
@@ -0,0 +1,110 @@
+using Microsoft.Extensions.Logging;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Calculation;
+
+/// <summary>
+///     Periodic re-evaluation scheduler for calc tags carrying a <c>timerIntervalMs</c>. A deliberate
+///     mirror of the VirtualTag <c>TimerTriggerScheduler</c> (<c>Core.VirtualTags</c>): one
+///     <see cref="System.Threading.Timer"/> per distinct interval group (so the wire count stays low
+///     regardless of tag count) with a per-group in-flight flag that skips a tick when the prior tick for
+///     the same group is still running. Revived <b>inside the driver</b> because the VT scheduler is welded
+///     to <c>VirtualTagEngine.EvaluateOneAsync</c>; here each tick invokes the driver's own evaluate
+///     callback per tag in the group.
+/// </summary>
+internal sealed class CalculationTimerScheduler : IDisposable
+{
+    private readonly Action<string> _evaluate;
+    private readonly ILogger _logger;
+    private readonly List<Timer> _timers = [];
+    private readonly List<TickGroup> _groups = [];
+    private readonly CancellationTokenSource _cts = new();
+    private long _skippedTickCount;
+    private bool _disposed;
+
+    /// <summary>Initializes a new instance of the <see cref="CalculationTimerScheduler"/> class.</summary>
+    /// <param name="evaluate">Callback invoked with a calc tag's RawPath when its timer group ticks.</param>
+    /// <param name="logger">Logger for diagnostics.</param>
+    public CalculationTimerScheduler(Action<string> evaluate, ILogger logger)
+    {
+        _evaluate = evaluate ?? throw new ArgumentNullException(nameof(evaluate));
+        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
+    }
+
+    /// <summary>Number of timer callbacks that skipped their work because the prior tick for the same
+    /// group was still running. Monotonic; exposed for tests + operational metrics.</summary>
+    public long SkippedTickCount => Interlocked.Read(ref _skippedTickCount);
+
+    /// <summary>Stand up one <see cref="Timer"/> per distinct interval. All tags sharing an interval share
+    /// a timer; each tick re-evaluates every tag in the group.</summary>
+    /// <param name="tags">The calc tags to schedule (only those with a positive <see cref="CalculationTagDefinition.TimerInterval"/> are scheduled).</param>
+    public void Start(IEnumerable<CalculationTagDefinition> tags)
+    {
+        ArgumentNullException.ThrowIfNull(tags);
+        if (_disposed) throw new ObjectDisposedException(nameof(CalculationTimerScheduler));
+
+        var byInterval = tags
+            .Where(t => t.TimerInterval is { } iv && iv > TimeSpan.Zero)
+            .GroupBy(t => t.TimerInterval!.Value);
+
+        foreach (var group in byInterval)
+        {
+            var paths = group.Select(t => t.RawPath).ToArray();
+            var interval = group.Key;
+            var ctx = new TickGroup(paths);
+            _groups.Add(ctx);
+            var timer = new Timer(_ => OnTimer(ctx), null, interval, interval);
+            _timers.Add(timer);
+            _logger.LogInformation("CalculationTimerScheduler: {TagCount} tag(s) on {Interval} cadence",
+                paths.Length, interval);
+        }
+    }
+
+    private void OnTimer(TickGroup ctx)
+    {
+        if (_cts.IsCancellationRequested) return;
+
+        // Skip the tick when the prior one for this group is still running — bounds the outstanding
+        // work to one tick per group regardless of how long an evaluation takes.
+        if (Interlocked.CompareExchange(ref ctx.InFlight, 1, 0) != 0)
+        {
+            Interlocked.Increment(ref _skippedTickCount);
+            return;
+        }
+
+        try
+        {
+            foreach (var path in ctx.Paths)
+            {
+                if (_cts.IsCancellationRequested) return;
+                try { _evaluate(path); }
+                catch (Exception ex) { _logger.LogError(ex, "CalculationTimerScheduler evaluate failed for {Path}", path); }
+            }
+        }
+        finally
+        {
+            Interlocked.Exchange(ref ctx.InFlight, 0);
+        }
+    }
+
+    /// <summary>Releases all timers and disposes the scheduler's resources.</summary>
+    public void Dispose()
+    {
+        if (_disposed) return;
+        _disposed = true;
+        _cts.Cancel();
+        foreach (var t in _timers)
+        {
+            try { t.Dispose(); } catch { /* best-effort teardown */ }
+        }
+        _timers.Clear();
+        _groups.Clear();
+        _cts.Dispose();
+    }
+
+    private sealed class TickGroup(IReadOnlyList<string> paths)
+    {
+        // 0 = idle, 1 = a tick is currently running for this group.
+        public int InFlight;
+        public IReadOnlyList<string> Paths { get; } = paths;
+    }
+}
@@ -0,0 +1,33 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+    <PropertyGroup>
+        <TargetFramework>net10.0</TargetFramework>
+        <Nullable>enable</Nullable>
+        <ImplicitUsings>enable</ImplicitUsings>
+        <LangVersion>latest</LangVersion>
+        <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+        <GenerateDocumentationFile>true</GenerateDocumentationFile>
+        <NoWarn>$(NoWarn);CS1591</NoWarn>
+        <RootNamespace>ZB.MOM.WW.OtOpcUa.Driver.Calculation</RootNamespace>
+        <AssemblyName>ZB.MOM.WW.OtOpcUa.Driver.Calculation</AssemblyName>
+    </PropertyGroup>
+
+    <ItemGroup>
+        <!-- Scripting infra shared with the VirtualTag Roslyn evaluator. Core.Scripting brings
+             CompiledScriptCache / TimedScriptEvaluator / ScriptEvaluator / the sandbox exceptions /
+             ScriptRootLogger + ScriptLoggerFactory (and, transitively, Microsoft.CodeAnalysis
+             for CompilationErrorException). Core.Scripting.Abstractions owns VirtualTagContext +
+             PassthroughScript; Commons owns VirtualTagEvalResult + IScriptCacheOwner; Core.Abstractions
+             owns DataValueSnapshot. -->
+        <ProjectReference Include="..\..\Core\ZB.MOM.WW.OtOpcUa.Core.Abstractions\ZB.MOM.WW.OtOpcUa.Core.Abstractions.csproj"/>
+        <ProjectReference Include="..\..\Core\ZB.MOM.WW.OtOpcUa.Commons\ZB.MOM.WW.OtOpcUa.Commons.csproj"/>
+        <ProjectReference Include="..\..\Core\ZB.MOM.WW.OtOpcUa.Core\ZB.MOM.WW.OtOpcUa.Core.csproj"/>
+        <ProjectReference Include="..\..\Core\ZB.MOM.WW.OtOpcUa.Core.Scripting.Abstractions\ZB.MOM.WW.OtOpcUa.Core.Scripting.Abstractions.csproj"/>
+        <ProjectReference Include="..\..\Core\ZB.MOM.WW.OtOpcUa.Core.Scripting\ZB.MOM.WW.OtOpcUa.Core.Scripting.csproj"/>
+    </ItemGroup>
+
+    <ItemGroup>
+        <InternalsVisibleTo Include="ZB.MOM.WW.OtOpcUa.Driver.Calculation.Tests"/>
+    </ItemGroup>
+
+</Project>
@@ -5,6 +5,7 @@ using Microsoft.Extensions.Logging.Abstractions;
 using ZB.MOM.WW.MxGateway.Client;
 using ZB.MOM.WW.OtOpcUa.Commons.Browsing;
 using ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Config;
+using ZB.MOM.WW.Secrets.Abstractions;

 namespace ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Browser;

@@ -34,11 +35,14 @@ public sealed class GalaxyDriverBrowser : IDriverBrowser
    };

    private readonly ILogger<GalaxyDriverBrowser> _logger;
+    private readonly ISecretResolver _secretResolver;

    /// <summary>Creates a new browser. Logger defaults to <see cref="NullLogger{T}"/>.</summary>
+    /// <param name="secretResolver">Resolves the <c>secret:</c> arm of <c>Gateway.ApiKeySecretRef</c> (DI-injected).</param>
    /// <param name="logger">Optional logger; null is allowed for unit-test construction.</param>
-    public GalaxyDriverBrowser(ILogger<GalaxyDriverBrowser>? logger = null)
+    public GalaxyDriverBrowser(ISecretResolver secretResolver, ILogger<GalaxyDriverBrowser>? logger = null)
    {
+        _secretResolver = secretResolver ?? throw new ArgumentNullException(nameof(secretResolver));
        _logger = logger ?? NullLogger<GalaxyDriverBrowser>.Instance;
    }

@@ -68,7 +72,7 @@ public sealed class GalaxyDriverBrowser : IDriverBrowser
        if (string.IsNullOrWhiteSpace(opts.MxAccess.ClientName))
            throw new InvalidOperationException("Galaxy browser requires MxAccess.ClientName.");

-        var clientOpts = BuildClientOptions(opts.Gateway);
+        var clientOpts = await BuildClientOptionsAsync(opts.Gateway, cancellationToken).ConfigureAwait(false);

        // 30s wall-clock budget for the connect phase, linked to the caller's token so
        // an AdminUI cancel still wins early.
@@ -116,19 +120,28 @@ public sealed class GalaxyDriverBrowser : IDriverBrowser
    ///     Build the gateway client options from the form's Gateway section. Mirrors the
    ///     runtime driver's <c>GalaxyDriver.BuildClientOptions</c> field-for-field so the
    ///     gateway sees an identical option shape. The API-key reference is resolved via
-    ///     the shared <see cref="GalaxySecretRef.ResolveApiKey"/> in Driver.Galaxy.Contracts
+    ///     the shared <see cref="GalaxySecretRef.ResolveApiKeyAsync"/> in Driver.Galaxy.Contracts
    ///     (the same resolver the runtime driver uses), so browse and runtime stay in lock-step.
+    ///     The <c>secret:</c> arm is async, so the key is resolved into a local before the
+    ///     object initializer (you can't await inside one).
    /// </summary>
-    private MxGatewayClientOptions BuildClientOptions(GalaxyGatewayOptions gw) => new()
+    private async Task<MxGatewayClientOptions> BuildClientOptionsAsync(
+        GalaxyGatewayOptions gw, CancellationToken cancellationToken)
    {
-        Endpoint = new Uri(gw.Endpoint, UriKind.Absolute),
-        ApiKey = GalaxySecretRef.ResolveApiKey(gw.ApiKeySecretRef, _logger),
-        UseTls = gw.UseTls,
-        CaCertificatePath = gw.CaCertificatePath,
-        ConnectTimeout = TimeSpan.FromSeconds(gw.ConnectTimeoutSeconds),
-        DefaultCallTimeout = TimeSpan.FromSeconds(gw.DefaultCallTimeoutSeconds),
-        StreamTimeout = gw.StreamTimeoutSeconds > 0
-            ? TimeSpan.FromSeconds(gw.StreamTimeoutSeconds)
-            : null,
-    };
+        var apiKey = await GalaxySecretRef
+            .ResolveApiKeyAsync(gw.ApiKeySecretRef, _secretResolver, _logger, cancellationToken)
+            .ConfigureAwait(false);
+        return new MxGatewayClientOptions
+        {
+            Endpoint = new Uri(gw.Endpoint, UriKind.Absolute),
+            ApiKey = apiKey,
+            UseTls = gw.UseTls,
+            CaCertificatePath = gw.CaCertificatePath,
+            ConnectTimeout = TimeSpan.FromSeconds(gw.ConnectTimeoutSeconds),
+            DefaultCallTimeout = TimeSpan.FromSeconds(gw.DefaultCallTimeoutSeconds),
+            StreamTimeout = gw.StreamTimeoutSeconds > 0
+                ? TimeSpan.FromSeconds(gw.StreamTimeoutSeconds)
+                : null,
+        };
+    }
 }
@@ -43,12 +43,14 @@ public sealed record GalaxyDriverOptions(

 /// <summary>
 ///     Connection details for the MxAccess gateway. <see cref="ApiKeySecretRef"/> is
-///     resolved by <see cref="GalaxySecretRef.ResolveApiKey"/> at InitializeAsync time. Four forms
+///     resolved by <see cref="GalaxySecretRef.ResolveApiKeyAsync"/> at InitializeAsync time. Five forms
 ///     supported, in priority order:
 ///     <list type="bullet">
 ///       <item><c>env:NAME</c> — read from an environment variable (recommended for
 ///         production; the central config DB holds only the indirection, not the key).</item>
 ///       <item><c>file:PATH</c> — read from an ACL'd file outside the repo.</item>
+///       <item><c>secret:NAME</c> — resolved through the shared <c>ZB.MOM.WW.Secrets</c>
+///         encrypted store; fail-closed if absent (the production path).</item>
 ///       <item><c>dev:KEY</c> — explicit cleartext opt-in for dev rigs / parity tests;
 ///         no startup warning.</item>
 ///       <item>Anything else — treated as a literal cleartext API key for back-compat.
@@ -1,9 +1,10 @@
 using Microsoft.Extensions.Logging;
+using ZB.MOM.WW.Secrets.Abstractions;

 namespace ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Config;

 /// <summary>
-///     Resolves <c>Gateway.ApiKeySecretRef</c> to the actual API-key string. Four
+///     Resolves <c>Gateway.ApiKeySecretRef</c> to the actual API-key string. Five
 ///     forms supported, evaluated in order:
 ///     <list type="number">
 ///       <item><c>env:NAME</c> — reads <c>Environment.GetEnvironmentVariable(NAME)</c>.
@@ -15,12 +16,17 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Config;
 ///       <item><c>dev:KEY</c> — explicit cleartext literal. The <c>dev:</c> prefix
 ///         is a deliberate opt-in signal (dev box, parity rig) so the resolver
 ///         doesn't emit a warning; production should never use this arm.</item>
+///       <item><c>secret:NAME</c> — resolves NAME through the shared
+///         <c>ZB.MOM.WW.Secrets</c> <see cref="ISecretResolver"/> (the encrypted-at-rest
+///         store). Fail-closed: a <c>secret:</c> ref whose secret is absent/tombstoned
+///         throws rather than falling through to the literal arm — the production path
+///         that retires the cleartext <c>dev:</c>/literal-in-DB model.</item>
 ///       <item>Anything else — used as the literal API key for back-compat with
 ///         configs that pre-date this resolver. When a logger is supplied the
 ///         resolver emits a startup warning so an operator who accidentally
 ///         committed a cleartext key sees it.</item>
 ///     </list>
-///     A future PR can swap any of these arms for a DPAPI-backed lookup without
+///     A future PR can swap any of these arms for a different backing store without
 ///     changing the call site.
 /// </summary>
 /// <remarks>
@@ -31,18 +37,26 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Config;
 public static class GalaxySecretRef
 {
    /// <summary>
-    ///     Resolves the supplied secret reference. When the ref falls through to the
-    ///     back-compat literal arm (an unprefixed cleartext API key in
-    ///     <c>DriverConfig</c> JSON) and a <paramref name="logger"/> is supplied, emits
-    ///     a <see cref="LogLevel.Warning"/>. The <c>dev:</c> prefix is the explicit
-    ///     opt-in path that doesn't warn.
+    ///     Resolves the supplied secret reference. The <c>secret:NAME</c> arm resolves
+    ///     through <paramref name="resolver"/> and is fail-closed (throws when the secret
+    ///     is absent). When the ref falls through to the back-compat literal arm (an
+    ///     unprefixed cleartext API key in <c>DriverConfig</c> JSON) and a
+    ///     <paramref name="logger"/> is supplied, emits a <see cref="LogLevel.Warning"/>.
+    ///     The <c>dev:</c> prefix is the explicit opt-in path that doesn't warn.
    /// </summary>
    /// <param name="secretRef">The secret reference string to resolve.</param>
+    /// <param name="resolver">The shared secret resolver used by the <c>secret:</c> arm.</param>
    /// <param name="logger">Optional logger for warning on cleartext keys.</param>
+    /// <param name="ct">Cancellation token for the async <c>secret:</c> resolution.</param>
    /// <returns>The resolved API-key string.</returns>
-    public static string ResolveApiKey(string secretRef, ILogger? logger = null)
+    public static async Task<string> ResolveApiKeyAsync(
+        string secretRef,
+        ISecretResolver resolver,
+        ILogger? logger = null,
+        CancellationToken ct = default)
    {
        ArgumentException.ThrowIfNullOrEmpty(secretRef);
+        ArgumentNullException.ThrowIfNull(resolver);

        if (secretRef.StartsWith("env:", StringComparison.OrdinalIgnoreCase))
        {
@@ -76,6 +90,19 @@ public static class GalaxySecretRef
            return secretRef[4..];
        }

+        if (secretRef.StartsWith("secret:", StringComparison.OrdinalIgnoreCase))
+        {
+            // Production path: resolve the name through the shared encrypted secret store.
+            // Fail-closed — an absent/tombstoned secret throws rather than falling through
+            // to the literal arm (which would silently treat the ref string as the key).
+            var name = secretRef["secret:".Length..];
+            var value = await resolver.GetAsync(new SecretName(name), ct).ConfigureAwait(false);
+            return !string.IsNullOrEmpty(value)
+                ? value
+                : throw new InvalidOperationException(
+                    $"Galaxy.Gateway.ApiKeySecretRef='{secretRef}' resolves secret '{name}', but it is absent from the store (fail-closed).");
+        }
+
        // Back-compat literal arm. An unprefixed string is treated as the literal
        // API key — but emit a warning so an operator who accidentally committed a
        // cleartext key into DriverConfig sees it. Use the dev: prefix to suppress
@@ -13,5 +13,6 @@
        <ProjectReference Include="..\..\Core\ZB.MOM.WW.OtOpcUa.Core.Abstractions\ZB.MOM.WW.OtOpcUa.Core.Abstractions.csproj" />
        <!-- Logging abstraction needed by GalaxySecretRef.ResolveApiKey's optional warning logger. -->
        <PackageReference Include="Microsoft.Extensions.Logging.Abstractions" />
+        <PackageReference Include="ZB.MOM.WW.Secrets.Abstractions" />
    </ItemGroup>
 </Project>
@@ -8,6 +8,7 @@ using ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Browse;
 using ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Config;
 using ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Health;
 using ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Runtime;
+using ZB.MOM.WW.Secrets.Abstractions;

 namespace ZB.MOM.WW.OtOpcUa.Driver.Galaxy;

@@ -43,6 +44,12 @@ public sealed class GalaxyDriver
    private readonly GalaxyDriverOptions _options;
    private readonly ILogger<GalaxyDriver> _logger;

+    // Resolves the Gateway.ApiKeySecretRef secret: arm through the shared encrypted store.
+    // Injected via ctor (the production factory pulls it from DI). The internal test ctor
+    // defaults it to a null-object resolver so the 45 seam-injecting test call sites keep
+    // compiling; those tests never use a secret: ref (they inject seams or use env/file/literal).
+    private readonly ISecretResolver _secretResolver;
+
    // PR 4.1 — IGalaxyHierarchySource is the test seam for browse. When null, the driver
    // lazily builds a GatewayGalaxyHierarchySource around a GalaxyRepositoryClient on
    // first DiscoverAsync. Tests inject a fake source via the internal ctor to exercise
@@ -147,14 +154,17 @@ public sealed class GalaxyDriver
    /// <summary>Initializes a new instance of the <see cref="GalaxyDriver"/> class.</summary>
    /// <param name="driverInstanceId">The unique identifier for this driver instance.</param>
    /// <param name="options">The Galaxy driver configuration options.</param>
+    /// <param name="secretResolver">Resolves the <c>secret:</c> arm of <c>Gateway.ApiKeySecretRef</c>.</param>
    /// <param name="logger">Optional logger instance for diagnostics.</param>
    public GalaxyDriver(
        string driverInstanceId,
        GalaxyDriverOptions options,
+        ISecretResolver secretResolver,
        ILogger<GalaxyDriver>? logger = null)
        : this(driverInstanceId, options,
              hierarchySource: null, dataReader: null, dataWriter: null, subscriber: null,
-              alarmAcknowledger: null, alarmFeed: null, logger)
+              alarmAcknowledger: null, alarmFeed: null, logger,
+              secretResolver: secretResolver ?? throw new ArgumentNullException(nameof(secretResolver)))
    {
    }

@@ -173,6 +183,11 @@ public sealed class GalaxyDriver
    /// <param name="alarmAcknowledger">Optional custom alarm acknowledger for testing.</param>
    /// <param name="alarmFeed">Optional custom alarm feed for testing.</param>
    /// <param name="logger">Optional logger instance for diagnostics.</param>
+    /// <param name="secretResolver">
+    ///     Optional secret resolver for the <c>secret:</c> API-key arm. Defaults to a
+    ///     null-object resolver (returns null for every name) so seam-injecting tests that
+    ///     don't exercise a <c>secret:</c> ref need not supply one.
+    /// </param>
    internal GalaxyDriver(
        string driverInstanceId,
        GalaxyDriverOptions options,
@@ -182,13 +197,15 @@ public sealed class GalaxyDriver
        IGalaxySubscriber? subscriber = null,
        IGalaxyAlarmAcknowledger? alarmAcknowledger = null,
        IGalaxyAlarmFeed? alarmFeed = null,
-        ILogger<GalaxyDriver>? logger = null)
+        ILogger<GalaxyDriver>? logger = null,
+        ISecretResolver? secretResolver = null)
    {
        _driverInstanceId = !string.IsNullOrWhiteSpace(driverInstanceId)
            ? driverInstanceId
            : throw new ArgumentException("Driver instance id required.", nameof(driverInstanceId));
        _options = options ?? throw new ArgumentNullException(nameof(options));
        _logger = logger ?? NullLogger<GalaxyDriver>.Instance;
+        _secretResolver = secretResolver ?? NullSecretResolver.Instance;
        _hierarchySource = hierarchySource;
        _dataReader = dataReader;
        _dataWriter = dataWriter;
@@ -316,7 +333,7 @@ public sealed class GalaxyDriver
                _driverInstanceId);
        }

-        StartDeployWatcher();
+        await StartDeployWatcherAsync(cancellationToken).ConfigureAwait(false);
        _logger.LogInformation(
            "GalaxyDriver {InstanceId} initialized — endpoint={Endpoint} clientName={ClientName}",
            _driverInstanceId, _options.Gateway.Endpoint, _options.MxAccess.ClientName);
@@ -331,7 +348,7 @@ public sealed class GalaxyDriver
    /// </summary>
    private async Task BuildProductionRuntimeAsync(CancellationToken cancellationToken)
    {
-        var clientOptions = BuildClientOptions(_options.Gateway);
+        var clientOptions = await BuildClientOptionsAsync(_options.Gateway, cancellationToken).ConfigureAwait(false);
        _ownedMxClient = MxGatewayClient.Create(clientOptions);
        _ownedMxSession = new GalaxyMxSession(_options.MxAccess, _logger);
        await _ownedMxSession.ConnectAsync(clientOptions, cancellationToken).ConfigureAwait(false);
@@ -386,7 +403,7 @@ public sealed class GalaxyDriver
    private async Task ReopenAsync(CancellationToken cancellationToken)
    {
        if (_ownedMxSession is null) return;
-        var clientOptions = BuildClientOptions(_options.Gateway);
+        var clientOptions = await BuildClientOptionsAsync(_options.Gateway, cancellationToken).ConfigureAwait(false);
        await _ownedMxSession.RecreateAsync(clientOptions, cancellationToken).ConfigureAwait(false);
        // The recreated session invalidates every prior gw item handle; drop the writer's handle/advise
        // caches so the next write re-AddItems + re-AdviseSupervisory against the fresh session.
@@ -527,32 +544,42 @@ public sealed class GalaxyDriver
        }
    }

-    private MxGatewayClientOptions BuildClientOptions(GalaxyGatewayOptions gw) => new()
+    private async Task<MxGatewayClientOptions> BuildClientOptionsAsync(
+        GalaxyGatewayOptions gw, CancellationToken cancellationToken)
    {
-        Endpoint = new Uri(gw.Endpoint, UriKind.Absolute),
-        // Pass the logger so the literal-arm cleartext fallback surfaces a startup
-        // warning rather than silently shipping the key. The resolver lives in
-        // Driver.Galaxy.Contracts (GalaxySecretRef) so the runtime driver and the
-        // AdminUI browser share one implementation.
-        ApiKey = GalaxySecretRef.ResolveApiKey(gw.ApiKeySecretRef, _logger),
-        UseTls = gw.UseTls,
-        CaCertificatePath = gw.CaCertificatePath,
-        ConnectTimeout = TimeSpan.FromSeconds(gw.ConnectTimeoutSeconds),
-        DefaultCallTimeout = TimeSpan.FromSeconds(gw.DefaultCallTimeoutSeconds),
-        StreamTimeout = gw.StreamTimeoutSeconds > 0 ? TimeSpan.FromSeconds(gw.StreamTimeoutSeconds) : null,
-    };
+        // Resolve the API-key ref BEFORE the object initializer — the secret: arm is
+        // async and you can't await inside an initializer. Pass the logger so the
+        // literal-arm cleartext fallback surfaces a startup warning rather than
+        // silently shipping the key. The resolver lives in Driver.Galaxy.Contracts
+        // (GalaxySecretRef) so the runtime driver and the AdminUI browser share one
+        // implementation; the secret: arm resolves through the shared ISecretResolver.
+        var apiKey = await GalaxySecretRef
+            .ResolveApiKeyAsync(gw.ApiKeySecretRef, _secretResolver, _logger, cancellationToken)
+            .ConfigureAwait(false);
+        return new MxGatewayClientOptions
+        {
+            Endpoint = new Uri(gw.Endpoint, UriKind.Absolute),
+            ApiKey = apiKey,
+            UseTls = gw.UseTls,
+            CaCertificatePath = gw.CaCertificatePath,
+            ConnectTimeout = TimeSpan.FromSeconds(gw.ConnectTimeoutSeconds),
+            DefaultCallTimeout = TimeSpan.FromSeconds(gw.DefaultCallTimeoutSeconds),
+            StreamTimeout = gw.StreamTimeoutSeconds > 0 ? TimeSpan.FromSeconds(gw.StreamTimeoutSeconds) : null,
+        };
+    }

-    private void StartDeployWatcher()
+    private async Task StartDeployWatcherAsync(CancellationToken cancellationToken)
    {
        if (!_options.Repository.WatchDeployEvents) return;
        if (_ownedRepositoryClient is null && _hierarchySource is null) return;

        // Reuse the lazily-built repository client (DiscoverAsync constructs it on demand).
        // If discovery hasn't run yet, build the client here so the watcher has a target.
-        // Guard with ??= so if BuildDefaultHierarchySource later runs it reuses this client
-        // rather than overwriting the field and leaking the first instance.
+        // Build under a null-check (not ??=) so if BuildDefaultHierarchySourceAsync later
+        // runs it reuses this client rather than overwriting the field and leaking the
+        // first instance — the client-options build is now async (secret: arm).
        _ownedRepositoryClient ??= ZB.MOM.WW.MxGateway.Client.GalaxyRepositoryClient.Create(
-            BuildClientOptions(_options.Gateway));
+            await BuildClientOptionsAsync(_options.Gateway, cancellationToken).ConfigureAwait(false));

        var source = new GatewayGalaxyDeployWatchSource(_ownedRepositoryClient);
        _deployWatcher = new DeployWatcher(source, _logger);
@@ -691,7 +718,8 @@ public sealed class GalaxyDriver
        // After discovery, SyncPlatformsAsync refreshes the probe watcher's membership so
        // newly added $WinPlatform / $AppEngine objects start advising their ScanState attribute.
        var capturingBuilder = new SecurityCapturingBuilder(builder, _securityByFullRef);
-        var source = _hierarchySource ??= BuildDefaultHierarchySource();
+        var source = _hierarchySource ??=
+            await BuildDefaultHierarchySourceAsync(cancellationToken).ConfigureAwait(false);
        // Thread the v3 reverse resolver so the discoverer emits each authored attribute's RawPath as
        // its node reference (FullName) — the security map SecurityCapturingBuilder captures is then
        // keyed by RawPath, matching what WriteAsync resolves against.
@@ -1292,12 +1320,14 @@ public sealed class GalaxyDriver
    ///     <see cref="Dispose"/>. Tests bypass this by injecting their own source via the
    ///     internal ctor.
    /// </summary>
-    private IGalaxyHierarchySource BuildDefaultHierarchySource()
+    private async Task<IGalaxyHierarchySource> BuildDefaultHierarchySourceAsync(CancellationToken cancellationToken)
    {
-        // Reuse a client that StartDeployWatcher may have already created (??=) rather
+        // Reuse a client that StartDeployWatcherAsync may have already created (??=) rather
        // than always overwriting the field and leaking the first instance. Both paths
-        // produce equivalent clients from the same options.
-        _ownedRepositoryClient ??= GalaxyRepositoryClient.Create(BuildClientOptions(_options.Gateway));
+        // produce equivalent clients from the same options. The client-options build is
+        // async now (secret: arm resolves through the shared ISecretResolver).
+        _ownedRepositoryClient ??= GalaxyRepositoryClient.Create(
+            await BuildClientOptionsAsync(_options.Gateway, cancellationToken).ConfigureAwait(false));
        return new TracedGalaxyHierarchySource(
            new GatewayGalaxyHierarchySource(_ownedRepositoryClient), _options.MxAccess.ClientName);
    }
@@ -4,6 +4,7 @@ using Microsoft.Extensions.Logging;
 using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
 using ZB.MOM.WW.OtOpcUa.Core.Hosting;
 using ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Config;
+using ZB.MOM.WW.Secrets.Abstractions;

 namespace ZB.MOM.WW.OtOpcUa.Driver.Galaxy;

@@ -23,30 +24,45 @@ public static class GalaxyDriverFactoryExtensions
 {
    public const string DriverTypeName = "GalaxyMxGateway";

-    /// <summary>Registers the Galaxy driver factory with the given registry and optional logger factory.</summary>
+    /// <summary>Registers the Galaxy driver factory with the given registry, secret resolver, and optional logger factory.</summary>
    /// <param name="registry">The driver factory registry to register with.</param>
+    /// <param name="secretResolver">
+    ///     The shared secret resolver (from DI) used to resolve the <c>secret:</c> arm of
+    ///     each instance's <c>Gateway.ApiKeySecretRef</c>.
+    /// </param>
    /// <param name="loggerFactory">The optional logger factory for creating drivers.</param>
-    public static void Register(DriverFactoryRegistry registry, ILoggerFactory? loggerFactory = null)
+    public static void Register(
+        DriverFactoryRegistry registry,
+        ISecretResolver secretResolver,
+        ILoggerFactory? loggerFactory = null)
    {
        ArgumentNullException.ThrowIfNull(registry);
-        registry.Register(DriverTypeName, (id, json) => CreateInstance(id, json, loggerFactory));
+        ArgumentNullException.ThrowIfNull(secretResolver);
+        registry.Register(DriverTypeName, (id, json) => CreateInstance(id, json, loggerFactory, secretResolver));
    }

-    /// <summary>Convenience for tests + standalone callers.</summary>
+    /// <summary>
+    ///     Convenience for tests + standalone callers. Uses the <see cref="NullSecretResolver"/>
+    ///     null-object, so the <c>secret:</c> API-key arm resolves fail-closed (absent) — callers
+    ///     that need a working <c>secret:</c> ref must use the <see cref="Register"/> path that
+    ///     threads the DI resolver.
+    /// </summary>
    /// <param name="driverInstanceId">The unique identifier for the driver instance.</param>
    /// <param name="driverConfigJson">The driver configuration in JSON format.</param>
    /// <returns>The constructed Galaxy driver instance.</returns>
    public static GalaxyDriver CreateInstance(string driverInstanceId, string driverConfigJson)
-        => CreateInstance(driverInstanceId, driverConfigJson, loggerFactory: null);
+        => CreateInstance(driverInstanceId, driverConfigJson, loggerFactory: null, NullSecretResolver.Instance);

-    /// <summary>Creates a Galaxy driver instance from configuration JSON with optional logger factory.</summary>
+    /// <summary>Creates a Galaxy driver instance from configuration JSON with optional logger factory and a secret resolver.</summary>
    /// <param name="driverInstanceId">The unique identifier for the driver instance.</param>
    /// <param name="driverConfigJson">The driver configuration in JSON format.</param>
    /// <param name="loggerFactory">The optional logger factory for creating drivers.</param>
+    /// <param name="secretResolver">The secret resolver for the driver's <c>secret:</c> API-key arm.</param>
    /// <returns>The constructed Galaxy driver instance.</returns>
    public static GalaxyDriver CreateInstance(
-        string driverInstanceId, string driverConfigJson, ILoggerFactory? loggerFactory)
+        string driverInstanceId, string driverConfigJson, ILoggerFactory? loggerFactory, ISecretResolver secretResolver)
    {
+        ArgumentNullException.ThrowIfNull(secretResolver);
        ArgumentException.ThrowIfNullOrWhiteSpace(driverInstanceId);
        ArgumentException.ThrowIfNullOrWhiteSpace(driverConfigJson);

@@ -88,7 +104,7 @@ public static class GalaxyDriverFactoryExtensions
            RawTags = dto.RawTags ?? [],
        };

-        return new GalaxyDriver(driverInstanceId, options, loggerFactory?.CreateLogger<GalaxyDriver>());
+        return new GalaxyDriver(driverInstanceId, options, secretResolver, loggerFactory?.CreateLogger<GalaxyDriver>());
    }

    private static readonly JsonSerializerOptions JsonOptions = new()
@@ -0,0 +1,26 @@
+using ZB.MOM.WW.Secrets.Abstractions;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Galaxy;
+
+/// <summary>
+///     A null-object <see cref="ISecretResolver"/> that resolves every name to <c>null</c>
+///     (absent). Used as the default for the internal test ctor and the parse-only
+///     <c>CreateInstance</c> path so callers that never exercise a <c>secret:</c> API-key
+///     ref need not thread a real resolver. A production <c>GalaxyDriver</c> always receives
+///     the DI-registered resolver via the factory; a <c>secret:</c> ref resolved against this
+///     null object throws fail-closed (the secret is reported absent), which is the correct
+///     behaviour for a mis-wired deployment.
+/// </summary>
+internal sealed class NullSecretResolver : ISecretResolver
+{
+    /// <summary>The shared singleton instance.</summary>
+    public static readonly NullSecretResolver Instance = new();
+
+    private NullSecretResolver()
+    {
+    }
+
+    /// <inheritdoc />
+    public Task<string?> GetAsync(SecretName name, CancellationToken ct) =>
+        Task.FromResult<string?>(null);
+}
@@ -14,7 +14,9 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient;
 ///     exposes PLC data" flow. Tier A (pure managed, OPC Foundation reference SDK); universal
 ///     protections cover it.
 /// </remarks>
-public sealed class OpcUaClientDriverOptions
+// A record (not a plain class) so G-2b's OpcUaClientSecretResolution can produce a
+// credential-resolved copy with a `with` expression — every property keeps its init setter.
+public sealed record OpcUaClientDriverOptions
 {
    /// <summary>
    ///     Remote OPC UA endpoint URL, e.g. <c>opc.tcp://plc.internal:4840</c>. Convenience
@@ -0,0 +1,26 @@
+using ZB.MOM.WW.Secrets.Abstractions;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient;
+
+/// <summary>
+///     A null-object <see cref="ISecretResolver"/> that resolves every name to <c>null</c>
+///     (absent). Backs the driver's default (test/parse-only) construction path so callers that
+///     never author a <c>secret:</c> credential ref need not thread a real resolver. A production
+///     <c>OpcUaClientDriver</c> always receives the DI-registered resolver via the factory; a
+///     <c>secret:</c> ref resolved against this null object throws fail-closed (the secret is
+///     reported absent), which is the correct behaviour for a mis-wired deployment — the
+///     <c>secret:</c> literal is never sent verbatim as a password.
+/// </summary>
+internal sealed class NullSecretResolver : ISecretResolver
+{
+    /// <summary>The shared singleton instance.</summary>
+    public static readonly NullSecretResolver Instance = new();
+
+    private NullSecretResolver()
+    {
+    }
+
+    /// <inheritdoc />
+    public Task<string?> GetAsync(SecretName name, CancellationToken ct) =>
+        Task.FromResult<string?>(null);
+}
@@ -4,6 +4,7 @@ using Opc.Ua;
 using Opc.Ua.Client;
 using Opc.Ua.Configuration;
 using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+using ZB.MOM.WW.Secrets.Abstractions;

 namespace ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient;

@@ -36,15 +37,25 @@ public sealed class OpcUaClientDriver : IDriver, ITagDiscovery, IReadable, IWrit
    /// <param name="options">Driver configuration.</param>
    /// <param name="driverInstanceId">Stable logical ID from the config DB.</param>
    /// <param name="logger">Optional logger; defaults to NullLogger when not supplied.</param>
+    /// <param name="secretResolver">
+    ///     Optional shared secret resolver used to resolve <c>secret:</c>-prefixed
+    ///     <see cref="OpcUaClientDriverOptions.Password"/> /
+    ///     <see cref="OpcUaClientDriverOptions.UserCertificatePassword"/> at session-open.
+    ///     Defaults to the <see cref="NullSecretResolver"/> null-object (which reports every
+    ///     secret absent) for the test/parse-only path; the production factory threads the
+    ///     DI-registered resolver. A <c>secret:</c> ref against the null-object fails closed.
+    /// </param>
    public OpcUaClientDriver(OpcUaClientDriverOptions options, string driverInstanceId,
-        ILogger<OpcUaClientDriver>? logger = null)
+        ILogger<OpcUaClientDriver>? logger = null, ISecretResolver? secretResolver = null)
    {
        _options = options;
        _driverInstanceId = driverInstanceId;
        _logger = logger ?? NullLogger<OpcUaClientDriver>.Instance;
+        _secretResolver = secretResolver ?? NullSecretResolver.Instance;
    }

    private readonly OpcUaClientDriverOptions _options;
+    private readonly ISecretResolver _secretResolver;
    private readonly string _driverInstanceId;
    // ---- IAlarmSource state ----

@@ -159,7 +170,18 @@ public sealed class OpcUaClientDriver : IDriver, ITagDiscovery, IReadable, IWrit
            var appConfig = await BuildApplicationConfigurationAsync(cancellationToken).ConfigureAwait(false);
            var candidates = ResolveEndpointCandidates(_options);

-            var identity = BuildUserIdentity(_options);
+            // G-2b: resolve any secret:-prefixed Password / UserCertificatePassword through the
+            // shared secret store ONCE, here in the async connect flow, just before the credentials
+            // are consumed. _options stays the raw config (with secret: refs) — only this
+            // connect-scoped local carries plaintext, and only for the duration of the connect.
+            // Resolving on every InitializeAsync (a full reconnect calls it) picks up rotations.
+            // Both credential consumers — the Username password below and the Certificate password
+            // in BuildCertificateIdentity — flow through BuildUserIdentity(resolvedOptions), so a
+            // single resolve covers both paths.
+            var resolvedOptions = await OpcUaClientSecretResolution
+                .ResolveSecretRefsAsync(_options, _secretResolver, cancellationToken).ConfigureAwait(false);
+
+            var identity = BuildUserIdentity(resolvedOptions);

            // Failover sweep: try each endpoint in order, return the session from the first
            // one that successfully connects. Per-endpoint failures are captured so the final
@@ -2,6 +2,7 @@ using System.Text.Json;
 using System.Text.Json.Serialization;
 using Microsoft.Extensions.Logging;
 using ZB.MOM.WW.OtOpcUa.Core.Hosting;
+using ZB.MOM.WW.Secrets.Abstractions;

 namespace ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient;

@@ -31,22 +32,37 @@ public static class OpcUaClientDriverFactoryExtensions
        Converters = { new JsonStringEnumConverter() },
    };

-    /// <summary>Register the OpcUaClient factory with the driver registry.</summary>
+    /// <summary>Register the OpcUaClient factory with the driver registry, threading the shared secret resolver.</summary>
    /// <param name="registry">The driver factory registry to register with.</param>
    /// <param name="loggerFactory">Optional logger factory used to create per-instance loggers.</param>
-    public static void Register(DriverFactoryRegistry registry, ILoggerFactory? loggerFactory = null)
+    /// <param name="secretResolver">
+    ///     The shared secret resolver (from DI) used to resolve the <c>secret:</c> arm of each
+    ///     instance's <c>Password</c> / <c>UserCertificatePassword</c> at session-open. Defaults to
+    ///     the <see cref="NullSecretResolver"/> null-object for the test/standalone path — callers
+    ///     that need a working <c>secret:</c> credential ref must thread the DI resolver.
+    /// </param>
+    public static void Register(
+        DriverFactoryRegistry registry,
+        ILoggerFactory? loggerFactory = null,
+        ISecretResolver? secretResolver = null)
    {
        ArgumentNullException.ThrowIfNull(registry);
-        registry.Register(DriverTypeName, (id, json) => CreateInstance(id, json, loggerFactory));
+        var resolver = secretResolver ?? NullSecretResolver.Instance;
+        registry.Register(DriverTypeName, (id, json) => CreateInstance(id, json, loggerFactory, resolver));
    }

    /// <summary>Public for the Server-side bootstrapper + test consumers.</summary>
    /// <param name="driverInstanceId">The unique identifier for the driver instance.</param>
    /// <param name="driverConfigJson">The JSON configuration string for the driver.</param>
    /// <param name="loggerFactory">Optional logger factory for the per-instance logger.</param>
+    /// <param name="secretResolver">
+    ///     Optional shared secret resolver for the driver's <c>secret:</c> credential arm; defaults
+    ///     to the <see cref="NullSecretResolver"/> null-object (fail-closed on a <c>secret:</c> ref).
+    /// </param>
    /// <returns>A configured <see cref="OpcUaClientDriver"/>.</returns>
    public static OpcUaClientDriver CreateInstance(
-        string driverInstanceId, string driverConfigJson, ILoggerFactory? loggerFactory = null)
+        string driverInstanceId, string driverConfigJson, ILoggerFactory? loggerFactory = null,
+        ISecretResolver? secretResolver = null)
    {
        ArgumentException.ThrowIfNullOrWhiteSpace(driverInstanceId);
        ArgumentException.ThrowIfNullOrWhiteSpace(driverConfigJson);
@@ -55,6 +71,8 @@ public static class OpcUaClientDriverFactoryExtensions
            ?? throw new InvalidOperationException(
                $"OpcUaClient driver config for '{driverInstanceId}' deserialised to null");

-        return new OpcUaClientDriver(options, driverInstanceId, loggerFactory?.CreateLogger<OpcUaClientDriver>());
+        return new OpcUaClientDriver(
+            options, driverInstanceId, loggerFactory?.CreateLogger<OpcUaClientDriver>(),
+            secretResolver ?? NullSecretResolver.Instance);
    }
 }
@@ -34,6 +34,12 @@ public sealed class OpcUaClientDriverProbe : IDriverProbe
    /// <inheritdoc />
    public async Task<DriverProbeResult> ProbeAsync(string configJson, TimeSpan timeout, CancellationToken ct)
    {
+        // G-2b note: the probe does an UNAUTHENTICATED GetEndpoints discovery preflight
+        // (BuildMinimalAppConfig sets no user identity) and never reads opts.Password /
+        // opts.UserCertificatePassword. Those credentials — including any secret: refs — are
+        // therefore intentionally NOT resolved here; resolving them would be dead code. Secret
+        // resolution happens lazily in OpcUaClientDriver's async session-open path, where the
+        // credentials are actually consumed.
        OpcUaClientDriverOptions? opts;
        try { opts = JsonSerializer.Deserialize<OpcUaClientDriverOptions>(configJson, _opts); }
        catch (Exception ex) { return new(false, $"Config JSON is invalid: {ex.Message}", null); }
@@ -0,0 +1,90 @@
+using ZB.MOM.WW.Secrets.Abstractions;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient;
+
+/// <summary>
+///     Layer-B (G-2b) secret resolution for the OPC UA Client driver's credential fields. Resolves
+///     <c>secret:</c>-prefixed <see cref="OpcUaClientDriverOptions.Password"/> and
+///     <see cref="OpcUaClientDriverOptions.UserCertificatePassword"/> through the shared
+///     <see cref="ISecretResolver"/> (the encrypted-at-rest store) just before the async
+///     session-open path consumes them — retiring the cleartext password-in-DB model for
+///     production.
+/// </summary>
+/// <remarks>
+///     Resolution is lazy (called from the connect flow, not at config deserialization) so a
+///     full reconnect via <c>InitializeAsync</c> re-resolves and picks up secret rotations,
+///     mirroring the Galaxy driver's re-resolve-on-reconnect behaviour. Only <c>secret:</c>-prefixed
+///     values are resolved; a null/empty or non-<c>secret:</c> value passes through verbatim so the
+///     literal-password back-compat path is preserved. The <c>secret:</c> arm is <b>fail-closed</b>:
+///     an absent/tombstoned secret throws rather than leaving the <c>secret:</c> literal in place,
+///     which would otherwise be sent verbatim to the remote server as the password.
+/// </remarks>
+internal static class OpcUaClientSecretResolution
+{
+    private const string SecretPrefix = "secret:";
+
+    /// <summary>
+    ///     Return a copy of <paramref name="options"/> with any <c>secret:</c>-prefixed
+    ///     <see cref="OpcUaClientDriverOptions.Password"/> /
+    ///     <see cref="OpcUaClientDriverOptions.UserCertificatePassword"/> resolved to their
+    ///     plaintext via <paramref name="resolver"/>. Non-secret / null / empty fields are
+    ///     returned unchanged.
+    /// </summary>
+    /// <param name="options">The raw driver options (credential fields may carry <c>secret:</c> refs).</param>
+    /// <param name="resolver">The shared secret resolver used by the <c>secret:</c> arm.</param>
+    /// <param name="ct">Cancellation token for the async secret resolution.</param>
+    /// <returns>An options copy whose credential fields carry resolved plaintext.</returns>
+    /// <exception cref="InvalidOperationException">
+    ///     A <c>secret:</c> ref names a secret that is absent/tombstoned in the store (fail-closed).
+    /// </exception>
+    internal static async Task<OpcUaClientDriverOptions> ResolveSecretRefsAsync(
+        OpcUaClientDriverOptions options, ISecretResolver resolver, CancellationToken ct)
+    {
+        ArgumentNullException.ThrowIfNull(options);
+        ArgumentNullException.ThrowIfNull(resolver);
+
+        var password = await ResolveFieldAsync(options.Password, nameof(options.Password), resolver, ct)
+            .ConfigureAwait(false);
+        var certPassword = await ResolveFieldAsync(
+            options.UserCertificatePassword, nameof(options.UserCertificatePassword), resolver, ct)
+            .ConfigureAwait(false);
+
+        // Only re-materialize when something actually changed — a `with` on the reference-equal
+        // strings is harmless, but skipping it keeps the common (no-secret) case allocation-free.
+        if (ReferenceEquals(password, options.Password)
+            && ReferenceEquals(certPassword, options.UserCertificatePassword))
+        {
+            return options;
+        }
+
+        return options with { Password = password, UserCertificatePassword = certPassword };
+    }
+
+    /// <summary>
+    ///     Resolve a single credential field. Null/empty or non-<c>secret:</c> values pass through
+    ///     unchanged (the reference-equal original is returned). A <c>secret:NAME</c> value is
+    ///     resolved through <paramref name="resolver"/> and is fail-closed when the secret is absent.
+    /// </summary>
+    /// <param name="value">The raw field value (may be a <c>secret:</c> ref).</param>
+    /// <param name="fieldName">The field name, used in the fail-closed exception message.</param>
+    /// <param name="resolver">The shared secret resolver.</param>
+    /// <param name="ct">Cancellation token for the async resolution.</param>
+    /// <returns>The resolved plaintext, or the original value when it is not a <c>secret:</c> ref.</returns>
+    private static async Task<string?> ResolveFieldAsync(
+        string? value, string fieldName, ISecretResolver resolver, CancellationToken ct)
+    {
+        if (string.IsNullOrEmpty(value)
+            || !value.StartsWith(SecretPrefix, StringComparison.OrdinalIgnoreCase))
+        {
+            return value;
+        }
+
+        var name = value[SecretPrefix.Length..];
+        var resolved = await resolver.GetAsync(new SecretName(name), ct).ConfigureAwait(false);
+        return !string.IsNullOrEmpty(resolved)
+            ? resolved
+            : throw new InvalidOperationException(
+                $"OpcUaClientDriverOptions.{fieldName}='{value}' resolves secret '{name}', but it is " +
+                "absent from the store (fail-closed).");
+    }
+}
@@ -21,6 +21,7 @@
    <ItemGroup>
        <PackageReference Include="OPCFoundation.NetStandard.Opc.Ua.Client"/>
        <PackageReference Include="OPCFoundation.NetStandard.Opc.Ua.Configuration"/>
+        <PackageReference Include="ZB.MOM.WW.Secrets.Abstractions"/>
    </ItemGroup>

    <ItemGroup>
@@ -0,0 +1,13 @@
+using ZB.MOM.WW.OtOpcUa.Commons.Browsing;
+
+namespace ZB.MOM.WW.OtOpcUa.AdminUI.Browsing;
+
+/// <summary>
+///     Payload for a leaf toggle in <c>DriverBrowseTree</c>'s multi-select mode (WP6 "Browse device…"
+///     re-target). Carries the toggled <see cref="Leaf"/> plus the captured browse-folder nesting above it
+///     (<see cref="FolderPath"/>, root→parent display names) so the browse modal can optionally mirror the
+///     nesting onto TagGroups on commit. Fired only for <see cref="BrowseNodeKind.Leaf"/> nodes.
+/// </summary>
+/// <param name="Leaf">The toggled leaf browse node (its <c>NodeId</c> is the driver full reference).</param>
+/// <param name="FolderPath">The ancestor folder display names, root→parent (empty for a top-level leaf).</param>
+public sealed record BrowseLeafSelection(BrowseNode Leaf, IReadOnlyList<string> FolderPath);
@@ -19,7 +19,11 @@
    <HeadOutlet/>
 </head>
 <body>
-    <Routes/>
+    @* No AdditionalAssemblies: the Secrets.Ui RCL's routable page is NOT routed directly in this
+       host — Pages/Secrets.razor wraps it so the route can carry this host's per-page
+       @rendermode (lmxopcua#483); registering the RCL routes too would make /admin/secrets
+       ambiguous. *@
+    <Routes />
    <script src="_content/ZB.MOM.WW.OtOpcUa.AdminUI/lib/bootstrap/js/bootstrap.bundle.min.js"></script>
    <ThemeScripts />
    <script src="_content/ZB.MOM.WW.OtOpcUa.AdminUI/js/monaco-init.js"></script>
@@ -16,9 +16,11 @@
            <NavRailItem Href="/hosts" Text="Host status" />
            <NavRailItem Href="/clusters" Text="Clusters" />
            <NavRailItem Href="/uns" Text="UNS" />
+            <NavRailItem Href="/raw" Text="Raw" />
            <NavRailItem Href="/reservations" Text="Reservations" />
            <NavRailItem Href="/certificates" Text="Certificates" />
            <NavRailItem Href="/role-grants" Text="Role grants" />
+            <NavRailItem Href="/admin/secrets" Text="Secrets" />
        </NavRailSection>
        <NavRailSection Title="Scripting" Key="scripting">
            <NavRailItem Href="/scripts" Text="Scripts" />
@@ -64,7 +64,22 @@ else
                        <tr>
                            <td><span class="mono small">@e.TimestampUtc.ToString("HH:mm:ss.fff")</span></td>
                            <td><span class="mono">@e.AlarmId</span><div class="text-muted small">@e.AlarmName</div></td>
-                            <td><span class="mono small">@e.EquipmentPath</span></td>
+                            <td>
+                                <span class="mono small">@e.EquipmentPath</span>
+                                @* v3 Batch 4 (multi-notifier native alarms): one condition row carries the list
+                                   of referencing equipment (Area/Line/Equipment) as display metadata. Shown only
+                                   when the producer populated it (native alarms whose raw tag ≥1 equipment
+                                   references); scripted alarms + unreferenced native alarms leave it empty. *@
+                                @if (e.ReferencingEquipmentPaths is { Count: > 0 } refs)
+                                {
+                                    <div class="text-muted small" title="Referencing equipment">
+                                        @foreach (var p in refs)
+                                        {
+                                            <span class="chip chip-idle" style="font-size:0.72rem; margin:1px">@p</span>
+                                        }
+                                    </div>
+                                }
+                            </td>
                            <td><span class="chip @KindChipClass(e.TransitionKind)">@e.TransitionKind</span></td>
                            <td class="num">@e.Severity</td>
                            <td>@e.User</td>
@@ -1,83 +0,0 @@
-@page "/clusters/{ClusterId}/drivers"
-@attribute [Authorize(Policy = AdminUiPolicies.AuthenticatedRead)]
-@rendermode RenderMode.InteractiveServer
-@using Microsoft.EntityFrameworkCore
-@using ZB.MOM.WW.OtOpcUa.Configuration
-@using ZB.MOM.WW.OtOpcUa.Configuration.Entities
-@inject IDbContextFactory<OtOpcUaConfigDbContext> DbFactory
-
-<div class="d-flex justify-content-between align-items-center mb-3">
-    <h4 class="mb-0">Drivers &middot; <span class="mono">@ClusterId</span></h4>
-    <a href="/clusters/@ClusterId/drivers/new" class="btn btn-primary btn-sm">New driver</a>
-</div>
-
-<ClusterNav ClusterId="@ClusterId" ActiveTab="drivers" />
-
-@if (_rows is null)
-{
-    <p>Loading…</p>
-}
-else
-{
-    <section class="panel rise mt-3" style="animation-delay:.08s">
-        <div class="panel-head">@_rows.Count driver instance@(_rows.Count == 1 ? "" : "s")</div>
-        @if (_rows.Count == 0)
-        {
-            <div style="padding:1rem" class="text-muted">No driver instances for this cluster.</div>
-        }
-        else
-        {
-            @foreach (var d in _rows)
-            {
-                <details style="border-top:1px solid var(--rule)">
-                    <summary style="padding:.75rem 1rem;cursor:pointer">
-                        <span class="mono">@d.DriverInstanceId</span>
-                        &middot; <span>@d.Name</span>
-                        &middot; <span class="chip chip-idle ms-1">@d.DriverType</span>
-                        @if (!d.Enabled) { <span class="chip chip-idle ms-1">Disabled</span> }
-                    </summary>
-                    <div style="padding:0 1rem 1rem">
-                        <div class="d-flex mb-2">
-                            <a href="/clusters/@ClusterId/drivers/@d.DriverInstanceId" class="btn btn-sm btn-outline-primary">Edit</a>
-                        </div>
-                        <pre class="mono small" style="background:var(--surface-2);padding:1rem;border-radius:4px;overflow:auto">@FormatJson(d.DriverConfig)</pre>
-                        @if (!string.IsNullOrWhiteSpace(d.ResilienceConfig))
-                        {
-                            <div class="text-muted small mt-2">Resilience overrides:</div>
-                            <pre class="mono small" style="background:var(--surface-2);padding:1rem;border-radius:4px;overflow:auto">@FormatJson(d.ResilienceConfig)</pre>
-                        }
-                    </div>
-                </details>
-            }
-        }
-    </section>
-}
-
-@code {
-    [Parameter] public string ClusterId { get; set; } = "";
-    private List<DriverInstance>? _rows;
-
-    protected override async Task OnInitializedAsync()
-    {
-        await using var db = await DbFactory.CreateDbContextAsync();
-        _rows = await db.DriverInstances.AsNoTracking()
-            .Where(d => d.ClusterId == ClusterId)
-            .OrderBy(d => d.DriverInstanceId)
-            .ToListAsync();
-    }
-
-    private static string FormatJson(string raw)
-    {
-        if (string.IsNullOrWhiteSpace(raw)) return "";
-        try
-        {
-            using var doc = System.Text.Json.JsonDocument.Parse(raw);
-            return System.Text.Json.JsonSerializer.Serialize(doc.RootElement,
-                new System.Text.Json.JsonSerializerOptions { WriteIndented = true });
-        }
-        catch
-        {
-            return raw;
-        }
-    }
-}
@@ -1,448 +0,0 @@
-@page "/clusters/{ClusterId}/drivers/new/abcip"
-@attribute [Authorize(Policy = AdminUiPolicies.ConfigEditor)]
-@rendermode RenderMode.InteractiveServer
-@using Microsoft.AspNetCore.Components.Forms
-@using Microsoft.EntityFrameworkCore
-@using ZB.MOM.WW.OtOpcUa.AdminUI.Clients
-@using ZB.MOM.WW.OtOpcUa.AdminUI.Components.Shared.Drivers
-@using ZB.MOM.WW.OtOpcUa.AdminUI.Components.Shared.Drivers.Pickers
-@using ZB.MOM.WW.OtOpcUa.Configuration
-@using ZB.MOM.WW.OtOpcUa.Configuration.Entities
-@using ZB.MOM.WW.OtOpcUa.Driver.AbCip
-@inject IDbContextFactory<OtOpcUaConfigDbContext> DbFactory
-@inject NavigationManager Nav
-
-<div class="d-flex justify-content-between align-items-center mb-3">
-    <h4 class="mb-0">@(IsNew ? "New AB CIP driver" : "Edit AB CIP driver") &middot; <span class="mono">@ClusterId</span></h4>
-    <a href="/clusters/@ClusterId/drivers" class="btn btn-outline-secondary btn-sm">Cancel</a>
-</div>
-<ClusterNav ClusterId="@ClusterId" ActiveTab="drivers" />
-
-@if (!_loaded)
-{
-    <p>Loading&hellip;</p>
-}
-else if (!IsNew && _existing is null)
-{
-    <section class="panel notice rise" style="animation-delay:.02s">
-        Driver instance <span class="mono">@DriverInstanceId</span> was not found in cluster <span class="mono">@ClusterId</span>.
-    </section>
-}
-else
-{
-    <EditForm Model="_form" OnValidSubmit="SubmitAsync" FormName="abcipDriverEdit">
-        <DataAnnotationsValidator />
-        <DriverFormShell IsNew="IsNew" Busy="_busy" Error="@_error"
-                         CancelHref="@($"/clusters/{ClusterId}/drivers")"
-                         OnDelete="@(IsNew ? null : (EventCallback?)EventCallback.Factory.Create(this, DeleteAsync))">
-
-            <DriverIdentitySection Model="_identityModel" IsNew="IsNew" ShowDriverType="false" />
-
-            @if (!IsNew && !string.IsNullOrEmpty(DriverInstanceId))
-            {
-                <DriverStatusPanel DriverInstanceId="@DriverInstanceId" Enabled="@_identityModel.Enabled" />
-            }
-
-            <div class="mt-2 mb-3">
-                <DriverTestConnectButton DriverType="@DriverTypeKey"
-                                         GetConfigJson="@SerializeCurrentConfig"
-                                         TimeoutSeconds="@_form.AdminProbeTimeoutSeconds" />
-                <button type="button" class="btn btn-sm btn-outline-secondary mt-2"
-                        @onclick="@(() => _showPicker = true)">
-                    Pick address
-                </button>
-            </div>
-
-            <DriverTagPicker @bind-Visible="_showPicker"
-                             Title="AB CIP address"
-                             CurrentAddress="@_pickedAddress"
-                             OnPickAddress="@OnAddressPicked">
-                <AbCipAddressPickerBody CurrentAddress="@_pickedAddress"
-                                        CurrentAddressChanged="@((s) => _pickedAddress = s)"
-                                        GetConfigJson="@SerializeCurrentConfig" />
-            </DriverTagPicker>
-
-            @* Operation timeout *@
-            <section class="panel rise mt-3" style="animation-delay:.06s">
-                <div class="panel-head">Operation settings</div>
-                <div style="padding:1rem">
-                    <div class="row g-3">
-                        <div class="col-md-3">
-                            <label class="form-label">Timeout (seconds)</label>
-                            <InputNumber @bind-Value="_form.TimeoutSeconds" class="form-control form-control-sm" />
-                            <div class="form-text">Default libplctag call timeout. Default 2 s.</div>
-                        </div>
-                        <div class="col-md-3">
-                            <div class="form-check form-switch mt-4">
-                                <InputCheckbox @bind-Value="_form.EnableControllerBrowse" class="form-check-input" id="enableBrowse" />
-                                <label class="form-check-label" for="enableBrowse">Enable controller browse</label>
-                            </div>
-                            <div class="form-text">Walk the Logix symbol table and surface globals under Discovered/.</div>
-                        </div>
-                        <div class="col-md-3">
-                            <div class="form-check form-switch mt-4">
-                                <InputCheckbox @bind-Value="_form.EnableDeclarationOnlyUdtGrouping" class="form-check-input" id="enableUdtGroup" />
-                                <label class="form-check-label" for="enableUdtGroup">Enable declaration-only UDT grouping</label>
-                            </div>
-                            <div class="form-text">Only enable when UDT member declaration order matches controller compiled layout.</div>
-                        </div>
-                    </div>
-                </div>
-            </section>
-
-            @* Alarm projection *@
-            <section class="panel rise mt-3" style="animation-delay:.08s">
-                <div class="panel-head">Alarm projection</div>
-                <div style="padding:1rem">
-                    <div class="row g-3">
-                        <div class="col-md-3">
-                            <div class="form-check form-switch mt-4">
-                                <InputCheckbox @bind-Value="_form.EnableAlarmProjection" class="form-check-input" id="enableAlarm" />
-                                <label class="form-check-label" for="enableAlarm">Enable ALMD alarm projection</label>
-                            </div>
-                            <div class="form-text">Surfaces ALMD tags as alarm conditions via IAlarmSource. Default off.</div>
-                        </div>
-                        <div class="col-md-3">
-                            <label class="form-label">Alarm poll interval (seconds)</label>
-                            <InputNumber @bind-Value="_form.AlarmPollIntervalSeconds" class="form-control form-control-sm" />
-                            <div class="form-text">Default 1 s.</div>
-                        </div>
-                    </div>
-                </div>
-            </section>
-
-            @* Connectivity probe *@
-            <section class="panel rise mt-3" style="animation-delay:.10s">
-                <div class="panel-head">Connectivity probe</div>
-                <div style="padding:1rem">
-                    <div class="row g-3">
-                        <div class="col-md-3">
-                            <div class="form-check form-switch mt-4">
-                                <InputCheckbox @bind-Value="_form.ProbeEnabled" class="form-check-input" id="probeEnabled" />
-                                <label class="form-check-label" for="probeEnabled">Enabled</label>
-                            </div>
-                        </div>
-                        <div class="col-md-3">
-                            <label class="form-label">Interval (seconds)</label>
-                            <InputNumber @bind-Value="_form.ProbeIntervalSeconds" class="form-control form-control-sm" />
-                            <div class="form-text">Default 5 s.</div>
-                        </div>
-                        <div class="col-md-3">
-                            <label class="form-label">Timeout (seconds)</label>
-                            <InputNumber @bind-Value="_form.ProbeTimeoutSeconds" class="form-control form-control-sm" />
-                            <div class="form-text">Default 2 s.</div>
-                        </div>
-                        <div class="col-md-3">
-                            <label class="form-label">Probe tag path</label>
-                            <InputText @bind-Value="_form.ProbeTagPath" class="form-control form-control-sm mono"
-                                       placeholder="e.g. Program:Main.SomeTag" />
-                            <div class="form-text">Required when probe is enabled. Leave blank and an operator warning is logged.</div>
-                        </div>
-                        <div class="col-md-3">
-                            <label class="form-label">Admin UI probe timeout (seconds)</label>
-                            <InputNumber @bind-Value="_form.AdminProbeTimeoutSeconds" class="form-control form-control-sm" />
-                            <div class="form-text">Max 60. Used by Test Connect. Default 5.</div>
-                        </div>
-                    </div>
-                </div>
-            </section>
-
-            @* Devices *@
-            <CollectionEditor TRow="AbCipDeviceRow" Items="_devices" Title="Devices" ItemNoun="device"
-                              AnimationDelay=".12s"
-                              NewRow="@(() => new AbCipDeviceRow())" Clone="@(r => r.Clone())"
-                              Validate="AbCipDeviceRow.ValidateRow">
-                <HeaderTemplate>
-                    <tr><th>Host address</th><th>PLC family</th><th>Device name</th><th></th></tr>
-                </HeaderTemplate>
-                <RowTemplate Context="d">
-                    <td class="mono">@d.HostAddress</td><td>@d.PlcFamily</td>
-                    <td>@(string.IsNullOrWhiteSpace(d.DeviceName) ? "—" : d.DeviceName)</td>
-                </RowTemplate>
-                <EditTemplate Context="d">
-                    <div class="row g-3">
-                        <div class="col-md-6"><label class="form-label">Host address</label>
-                            <input class="form-control form-control-sm mono" @bind="d.HostAddress"
-                                   placeholder="ab://gateway/1,0" /></div>
-                        <div class="col-md-3"><label class="form-label">PLC family</label>
-                            <select class="form-select form-select-sm" @bind="d.PlcFamily">
-                                @foreach (var e in Enum.GetValues<AbCipPlcFamily>()) { <option value="@e">@e</option> }
-                            </select></div>
-                        <div class="col-md-3"><label class="form-label">Device name</label>
-                            <input class="form-control form-control-sm" @bind="d.DeviceName" /></div>
-                    </div>
-                </EditTemplate>
-            </CollectionEditor>
-
-            @* Tags *@
-            <section class="panel notice rise mt-3" style="animation-delay:.18s">
-                <div class="panel-head">Tags</div>
-                <div style="padding:1rem" class="text-muted">
-                    Tag authoring moves to the Raw tree (<strong>/raw</strong>) in v3 Batch 2.
-                    Pre-declared driver tags have been retired.
-                </div>
-            </section>
-
-            <DriverResilienceSection @bind-ResilienceConfig="_form.ResilienceConfig" />
-        </DriverFormShell>
-    </EditForm>
-}
-
-@code {
-    [Parameter] public string ClusterId { get; set; } = "";
-    [Parameter] public string? DriverInstanceId { get; set; }
-
-    private const string DriverTypeKey = "AbCip";
-
-    private bool IsNew => string.IsNullOrEmpty(DriverInstanceId);
-
-    private static readonly System.Text.Json.JsonSerializerOptions _jsonOpts = new()
-    {
-        PropertyNamingPolicy = System.Text.Json.JsonNamingPolicy.CamelCase,
-        UnmappedMemberHandling = System.Text.Json.Serialization.JsonUnmappedMemberHandling.Skip,
-        WriteIndented = false,
-        Converters = { new System.Text.Json.Serialization.JsonStringEnumConverter() },
-    };
-
-    private FormModel _form = new();
-    private DriverIdentitySection.DriverIdentityModel _identityModel = new() { DriverType = DriverTypeKey };
-    private DriverInstance? _existing;
-    private bool _loaded;
-    private bool _busy;
-    private string? _error;
-
-    // Address picker state
-    private bool _showPicker;
-    private string _pickedAddress = "";
-
-    private void OnAddressPicked(string address) => _pickedAddress = address;
-
-    // Held separately because Devices is a collection — edited via the CollectionEditor modal.
-    private List<AbCipDeviceRow> _devices = [];
-
-    protected override async Task OnInitializedAsync()
-    {
-        await using var db = await DbFactory.CreateDbContextAsync();
-
-        if (IsNew)
-        {
-            _identityModel = new()
-            {
-                DriverInstanceId = "",
-                Name = "",
-                DriverType = DriverTypeKey,
-                Enabled = true,
-            };
-            _form = new FormModel();
-        }
-        else
-        {
-            _existing = await db.DriverInstances.AsNoTracking()
-                .FirstOrDefaultAsync(d => d.ClusterId == ClusterId && d.DriverInstanceId == DriverInstanceId);
-            if (_existing is not null)
-            {
-                _identityModel = new()
-                {
-                    DriverInstanceId = _existing.DriverInstanceId,
-                    Name = _existing.Name,
-                    DriverType = _existing.DriverType,
-                    Enabled = _existing.Enabled,
-                };
-                var opts = TryDeserialize(_existing.DriverConfig) ?? new AbCipDriverOptions();
-                _form = FormModel.FromOptions(opts);
-                _form.ResilienceConfig = _existing.ResilienceConfig;
-                _form.RowVersion = _existing.RowVersion;
-                _devices = opts.Devices.Select(AbCipDeviceRow.FromDefinition).ToList();
-            }
-        }
-        _loaded = true;
-    }
-
-    private async Task SubmitAsync()
-    {
-        _busy = true; _error = null;
-        try
-        {
-            var configJson = System.Text.Json.JsonSerializer.Serialize(
-                _form.ToOptions(
-                    _devices.Select(r => r.ToDefinition()).ToList()),
-                _jsonOpts);
-            await using var db = await DbFactory.CreateDbContextAsync();
-            if (IsNew)
-            {
-                if (await db.DriverInstances.AnyAsync(d => d.DriverInstanceId == _identityModel.DriverInstanceId))
-                {
-                    _error = $"Driver instance '{_identityModel.DriverInstanceId}' already exists.";
-                    return;
-                }
-                db.DriverInstances.Add(new DriverInstance
-                {
-                    DriverInstanceId = _identityModel.DriverInstanceId,
-                    ClusterId = ClusterId,
-                    Name = _identityModel.Name,
-                    DriverType = DriverTypeKey,
-                    Enabled = _identityModel.Enabled,
-                    DriverConfig = configJson,
-                    ResilienceConfig = string.IsNullOrWhiteSpace(_form.ResilienceConfig) ? null : _form.ResilienceConfig,
-                });
-            }
-            else
-            {
-                var entity = await db.DriverInstances.FirstOrDefaultAsync(
-                    d => d.ClusterId == ClusterId && d.DriverInstanceId == DriverInstanceId);
-                if (entity is null) { _error = "Row no longer exists."; return; }
-                db.Entry(entity).Property(e => e.RowVersion).OriginalValue = _form.RowVersion;
-                entity.Name = _identityModel.Name;
-                entity.Enabled = _identityModel.Enabled;
-                entity.DriverConfig = configJson;
-                entity.ResilienceConfig = string.IsNullOrWhiteSpace(_form.ResilienceConfig) ? null : _form.ResilienceConfig;
-            }
-            await db.SaveChangesAsync();
-            Nav.NavigateTo($"/clusters/{ClusterId}/drivers");
-        }
-        catch (DbUpdateConcurrencyException)
-        {
-            _error = "Another user changed this driver instance while you were editing. Reload to see the latest values, then re-apply your changes.";
-        }
-        catch (Exception ex) { _error = ex.Message; }
-        finally { _busy = false; }
-    }
-
-    private async Task DeleteAsync()
-    {
-        if (IsNew) return;
-        _busy = true; _error = null;
-        try
-        {
-            await using var db = await DbFactory.CreateDbContextAsync();
-            var entity = await db.DriverInstances.FirstOrDefaultAsync(
-                d => d.ClusterId == ClusterId && d.DriverInstanceId == DriverInstanceId);
-            if (entity is null) { Nav.NavigateTo($"/clusters/{ClusterId}/drivers"); return; }
-            db.Entry(entity).Property(e => e.RowVersion).OriginalValue = _form.RowVersion;
-            db.DriverInstances.Remove(entity);
-            await db.SaveChangesAsync();
-            Nav.NavigateTo($"/clusters/{ClusterId}/drivers");
-        }
-        catch (DbUpdateConcurrencyException)
-        {
-            _error = "Another user changed this driver instance while you were viewing it. Reload before deleting.";
-        }
-        catch (Exception ex)
-        {
-            _error = $"Delete failed: {ex.Message}. (Likely because equipment/tags still reference this driver — remove them first.)";
-        }
-        finally { _busy = false; }
-    }
-
-    private string SerializeCurrentConfig()
-        => System.Text.Json.JsonSerializer.Serialize(
-            _form.ToOptions(
-                _devices.Select(r => r.ToDefinition()).ToList()),
-            _jsonOpts);
-
-    private static AbCipDriverOptions? TryDeserialize(string json)
-    {
-        try { return System.Text.Json.JsonSerializer.Deserialize<AbCipDriverOptions>(json, _jsonOpts); }
-        catch { return null; }
-    }
-
-    // Mutable VM for the modal editor — AbCipDeviceOptions is an immutable record.
-    public sealed class AbCipDeviceRow
-    {
-        public string HostAddress { get; set; } = "";
-        public AbCipPlcFamily PlcFamily { get; set; } = AbCipPlcFamily.ControlLogix;
-        public string? DeviceName { get; set; }
-
-        // Original record (null for newly-added rows). Preserves fields the editor doesn't expose
-        // (AllowPacking, ConnectionSize) across a load→save.
-        private AbCipDeviceOptions? _source;
-
-        public AbCipDeviceRow Clone() => (AbCipDeviceRow)MemberwiseClone(); // _source is an immutable record ref — safe to share
-
-        public static AbCipDeviceRow FromDefinition(AbCipDeviceOptions d) => new()
-        {
-            HostAddress = d.HostAddress, PlcFamily = d.PlcFamily, DeviceName = d.DeviceName,
-            _source = d,
-        };
-
-        public AbCipDeviceOptions ToDefinition()
-        {
-            var baseDef = _source ?? new AbCipDeviceOptions(HostAddress.Trim(), PlcFamily);
-            return baseDef with
-            {
-                HostAddress = HostAddress.Trim(),
-                PlcFamily = PlcFamily,
-                DeviceName = string.IsNullOrWhiteSpace(DeviceName) ? null : DeviceName.Trim(),
-            };
-        }
-
-        public static string? ValidateRow(AbCipDeviceRow row, IReadOnlyList<AbCipDeviceRow> all, int? editIndex)
-        {
-            if (string.IsNullOrWhiteSpace(row.HostAddress)) return "Host address is required.";
-            for (var i = 0; i < all.Count; i++)
-                if (i != editIndex && string.Equals(all[i].HostAddress, row.HostAddress, StringComparison.OrdinalIgnoreCase))
-                    return $"Duplicate device host address '{row.HostAddress}'.";
-            return null;
-        }
-    }
-
-    // Flat mutable model — all scalar properties settable for Blazor @bind-Value.
-    // Collections (Devices) are kept on the component and passed in on ToOptions().
-    public sealed class FormModel
-    {
-        // Operation
-        public int TimeoutSeconds { get; set; } = 2;
-        public bool EnableControllerBrowse { get; set; } = false;
-        public bool EnableDeclarationOnlyUdtGrouping { get; set; } = false;
-
-        // Alarm projection
-        public bool EnableAlarmProjection { get; set; } = false;
-        public int AlarmPollIntervalSeconds { get; set; } = 1;
-
-        // Probe
-        public bool ProbeEnabled { get; set; } = true;
-        public int ProbeIntervalSeconds { get; set; } = 5;
-        public int ProbeTimeoutSeconds { get; set; } = 2;
-        public string? ProbeTagPath { get; set; }
-
-        // Admin UI probe timeout
-        public int AdminProbeTimeoutSeconds { get; set; } = 5;
-
-        // Persistence
-        public string? ResilienceConfig { get; set; }
-        public byte[] RowVersion { get; set; } = [];
-
-        public static FormModel FromOptions(AbCipDriverOptions o) => new()
-        {
-            TimeoutSeconds = (int)o.Timeout.TotalSeconds,
-            EnableControllerBrowse = o.EnableControllerBrowse,
-            EnableDeclarationOnlyUdtGrouping = o.EnableDeclarationOnlyUdtGrouping,
-            EnableAlarmProjection = o.EnableAlarmProjection,
-            AlarmPollIntervalSeconds = (int)o.AlarmPollInterval.TotalSeconds,
-            ProbeEnabled = o.Probe.Enabled,
-            ProbeIntervalSeconds = (int)o.Probe.Interval.TotalSeconds,
-            ProbeTimeoutSeconds = (int)o.Probe.Timeout.TotalSeconds,
-            ProbeTagPath = o.Probe.ProbeTagPath,
-            AdminProbeTimeoutSeconds = o.ProbeTimeoutSeconds,
-        };
-
-        public AbCipDriverOptions ToOptions(
-            IReadOnlyList<AbCipDeviceOptions> devices) => new()
-        {
-            Devices = devices,
-            Probe = new AbCipProbeOptions
-            {
-                Enabled = ProbeEnabled,
-                Interval = TimeSpan.FromSeconds(ProbeIntervalSeconds),
-                Timeout = TimeSpan.FromSeconds(ProbeTimeoutSeconds),
-                ProbeTagPath = string.IsNullOrWhiteSpace(ProbeTagPath) ? null : ProbeTagPath,
-            },
-            Timeout = TimeSpan.FromSeconds(TimeoutSeconds),
-            EnableControllerBrowse = EnableControllerBrowse,
-            EnableAlarmProjection = EnableAlarmProjection,
-            AlarmPollInterval = TimeSpan.FromSeconds(AlarmPollIntervalSeconds),
-            EnableDeclarationOnlyUdtGrouping = EnableDeclarationOnlyUdtGrouping,
-            ProbeTimeoutSeconds = AdminProbeTimeoutSeconds,
-        };
-    }
-}
@@ -1,399 +0,0 @@
-@page "/clusters/{ClusterId}/drivers/new/ablegacy"
-@attribute [Authorize(Policy = AdminUiPolicies.ConfigEditor)]
-@rendermode RenderMode.InteractiveServer
-@using Microsoft.AspNetCore.Components.Forms
-@using Microsoft.EntityFrameworkCore
-@using ZB.MOM.WW.OtOpcUa.AdminUI.Clients
-@using ZB.MOM.WW.OtOpcUa.AdminUI.Components.Shared.Drivers
-@using ZB.MOM.WW.OtOpcUa.AdminUI.Components.Shared.Drivers.Pickers
-@using ZB.MOM.WW.OtOpcUa.Configuration
-@using ZB.MOM.WW.OtOpcUa.Configuration.Entities
-@using ZB.MOM.WW.OtOpcUa.Driver.AbLegacy
-@using ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.PlcFamilies
-@inject IDbContextFactory<OtOpcUaConfigDbContext> DbFactory
-@inject NavigationManager Nav
-
-<div class="d-flex justify-content-between align-items-center mb-3">
-    <h4 class="mb-0">@(IsNew ? "New AB Legacy driver" : "Edit AB Legacy driver") &middot; <span class="mono">@ClusterId</span></h4>
-    <a href="/clusters/@ClusterId/drivers" class="btn btn-outline-secondary btn-sm">Cancel</a>
-</div>
-<ClusterNav ClusterId="@ClusterId" ActiveTab="drivers" />
-
-@if (!_loaded)
-{
-    <p>Loading&hellip;</p>
-}
-else if (!IsNew && _existing is null)
-{
-    <section class="panel notice rise" style="animation-delay:.02s">
-        Driver instance <span class="mono">@DriverInstanceId</span> was not found in cluster <span class="mono">@ClusterId</span>.
-    </section>
-}
-else
-{
-    <EditForm Model="_form" OnValidSubmit="SubmitAsync" FormName="ablegacyDriverEdit">
-        <DataAnnotationsValidator />
-        <DriverFormShell IsNew="IsNew" Busy="_busy" Error="@_error"
-                         CancelHref="@($"/clusters/{ClusterId}/drivers")"
-                         OnDelete="@(IsNew ? null : (EventCallback?)EventCallback.Factory.Create(this, DeleteAsync))">
-
-            <DriverIdentitySection Model="_identityModel" IsNew="IsNew" ShowDriverType="false" />
-
-            @if (!IsNew && !string.IsNullOrEmpty(DriverInstanceId))
-            {
-                <DriverStatusPanel DriverInstanceId="@DriverInstanceId" Enabled="@_identityModel.Enabled" />
-            }
-
-            <div class="mt-2 mb-3">
-                <DriverTestConnectButton DriverType="@DriverTypeKey"
-                                         GetConfigJson="@SerializeCurrentConfig"
-                                         TimeoutSeconds="@_form.AdminProbeTimeoutSeconds" />
-                <button type="button" class="btn btn-sm btn-outline-secondary mt-2"
-                        @onclick="@(() => _showPicker = true)">
-                    Pick address
-                </button>
-            </div>
-
-            <DriverTagPicker @bind-Visible="_showPicker"
-                             Title="AB Legacy address"
-                             CurrentAddress="@_pickedAddress"
-                             OnPickAddress="@OnAddressPicked">
-                <AbLegacyAddressPickerBody CurrentAddress="@_pickedAddress"
-                                           CurrentAddressChanged="@((s) => _pickedAddress = s)" />
-            </DriverTagPicker>
-
-            @* Operation settings *@
-            <section class="panel rise mt-3" style="animation-delay:.06s">
-                <div class="panel-head">Operation settings</div>
-                <div style="padding:1rem">
-                    <div class="row g-3">
-                        <div class="col-md-3">
-                            <label class="form-label">Timeout (seconds)</label>
-                            <InputNumber @bind-Value="_form.TimeoutSeconds" class="form-control form-control-sm" />
-                            <div class="form-text">Default read/write timeout. Default 2 s.</div>
-                        </div>
-                    </div>
-                </div>
-            </section>
-
-            @* Connectivity probe *@
-            <section class="panel rise mt-3" style="animation-delay:.08s">
-                <div class="panel-head">Connectivity probe</div>
-                <div style="padding:1rem">
-                    <div class="row g-3">
-                        <div class="col-md-3">
-                            <div class="form-check form-switch mt-4">
-                                <InputCheckbox @bind-Value="_form.ProbeEnabled" class="form-check-input" id="probeEnabled" />
-                                <label class="form-check-label" for="probeEnabled">Enabled</label>
-                            </div>
-                        </div>
-                        <div class="col-md-3">
-                            <label class="form-label">Interval (seconds)</label>
-                            <InputNumber @bind-Value="_form.ProbeIntervalSeconds" class="form-control form-control-sm" />
-                            <div class="form-text">Default 5 s.</div>
-                        </div>
-                        <div class="col-md-3">
-                            <label class="form-label">Timeout (seconds)</label>
-                            <InputNumber @bind-Value="_form.ProbeTimeoutSeconds" class="form-control form-control-sm" />
-                            <div class="form-text">Default 2 s.</div>
-                        </div>
-                        <div class="col-md-3">
-                            <label class="form-label">Probe address</label>
-                            <InputText @bind-Value="_form.ProbeAddress" class="form-control form-control-sm mono"
-                                       placeholder="S:0" />
-                            <div class="form-text">PCCC file address to read for probe. Default S:0 (status file word 0).</div>
-                        </div>
-                        <div class="col-md-3">
-                            <label class="form-label">Admin UI probe timeout (seconds)</label>
-                            <InputNumber @bind-Value="_form.AdminProbeTimeoutSeconds" class="form-control form-control-sm" />
-                            <div class="form-text">Max 60. Used by Test Connect. Default 5.</div>
-                        </div>
-                    </div>
-                </div>
-            </section>
-
-            @* Devices *@
-            <CollectionEditor TRow="AbLegacyDeviceRow" Items="_devices" Title="Devices" ItemNoun="device"
-                              AnimationDelay=".10s"
-                              NewRow="@(() => new AbLegacyDeviceRow())" Clone="@(r => r.Clone())"
-                              Validate="AbLegacyDeviceRow.ValidateRow">
-                <HeaderTemplate>
-                    <tr><th>Host address</th><th>PLC family</th><th>Device name</th><th></th></tr>
-                </HeaderTemplate>
-                <RowTemplate Context="d">
-                    <td class="mono">@d.HostAddress</td><td>@d.PlcFamily</td>
-                    <td>@(string.IsNullOrWhiteSpace(d.DeviceName) ? "—" : d.DeviceName)</td>
-                </RowTemplate>
-                <EditTemplate Context="d">
-                    <div class="row g-3">
-                        <div class="col-md-6"><label class="form-label">Host address</label>
-                            <input class="form-control form-control-sm mono" @bind="d.HostAddress"
-                                   placeholder="10.0.0.10" /></div>
-                        <div class="col-md-3"><label class="form-label">PLC family</label>
-                            <select class="form-select form-select-sm" @bind="d.PlcFamily">
-                                @foreach (var e in Enum.GetValues<AbLegacyPlcFamily>()) { <option value="@e">@e</option> }
-                            </select></div>
-                        <div class="col-md-3"><label class="form-label">Device name</label>
-                            <input class="form-control form-control-sm" @bind="d.DeviceName" /></div>
-                    </div>
-                </EditTemplate>
-            </CollectionEditor>
-
-            @* Tags *@
-            <section class="panel notice rise mt-3" style="animation-delay:.18s">
-                <div class="panel-head">Tags</div>
-                <div style="padding:1rem" class="text-muted">
-                    Tag authoring moves to the Raw tree (<strong>/raw</strong>) in v3 Batch 2.
-                    Pre-declared driver tags have been retired.
-                </div>
-            </section>
-
-            <DriverResilienceSection @bind-ResilienceConfig="_form.ResilienceConfig" />
-        </DriverFormShell>
-    </EditForm>
-}
-
-@code {
-    [Parameter] public string ClusterId { get; set; } = "";
-    [Parameter] public string? DriverInstanceId { get; set; }
-
-    private const string DriverTypeKey = "AbLegacy";
-
-    private bool IsNew => string.IsNullOrEmpty(DriverInstanceId);
-
-    private static readonly System.Text.Json.JsonSerializerOptions _jsonOpts = new()
-    {
-        PropertyNamingPolicy = System.Text.Json.JsonNamingPolicy.CamelCase,
-        UnmappedMemberHandling = System.Text.Json.Serialization.JsonUnmappedMemberHandling.Skip,
-        WriteIndented = false,
-        Converters = { new System.Text.Json.Serialization.JsonStringEnumConverter() },
-    };
-
-    private FormModel _form = new();
-    private DriverIdentitySection.DriverIdentityModel _identityModel = new() { DriverType = DriverTypeKey };
-    private DriverInstance? _existing;
-    private bool _loaded;
-    private bool _busy;
-    private string? _error;
-
-    // Address picker state
-    private bool _showPicker;
-    private string _pickedAddress = "";
-
-    private void OnAddressPicked(string address) => _pickedAddress = address;
-
-    // Held separately because Devices/Tags are collections — edited via the CollectionEditor modal.
-    private List<AbLegacyDeviceRow> _devices = [];
-
-    protected override async Task OnInitializedAsync()
-    {
-        await using var db = await DbFactory.CreateDbContextAsync();
-
-        if (IsNew)
-        {
-            _identityModel = new()
-            {
-                DriverInstanceId = "",
-                Name = "",
-                DriverType = DriverTypeKey,
-                Enabled = true,
-            };
-            _form = new FormModel();
-        }
-        else
-        {
-            _existing = await db.DriverInstances.AsNoTracking()
-                .FirstOrDefaultAsync(d => d.ClusterId == ClusterId && d.DriverInstanceId == DriverInstanceId);
-            if (_existing is not null)
-            {
-                _identityModel = new()
-                {
-                    DriverInstanceId = _existing.DriverInstanceId,
-                    Name = _existing.Name,
-                    DriverType = _existing.DriverType,
-                    Enabled = _existing.Enabled,
-                };
-                var opts = TryDeserialize(_existing.DriverConfig) ?? new AbLegacyDriverOptions();
-                _form = FormModel.FromOptions(opts);
-                _form.ResilienceConfig = _existing.ResilienceConfig;
-                _form.RowVersion = _existing.RowVersion;
-                _devices = opts.Devices.Select(AbLegacyDeviceRow.FromDefinition).ToList();
-            }
-        }
-        _loaded = true;
-    }
-
-    private async Task SubmitAsync()
-    {
-        _busy = true; _error = null;
-        try
-        {
-            var configJson = System.Text.Json.JsonSerializer.Serialize(
-                _form.ToOptions(
-                    _devices.Select(r => r.ToDefinition()).ToList()),
-                _jsonOpts);
-            await using var db = await DbFactory.CreateDbContextAsync();
-            if (IsNew)
-            {
-                if (await db.DriverInstances.AnyAsync(d => d.DriverInstanceId == _identityModel.DriverInstanceId))
-                {
-                    _error = $"Driver instance '{_identityModel.DriverInstanceId}' already exists.";
-                    return;
-                }
-                db.DriverInstances.Add(new DriverInstance
-                {
-                    DriverInstanceId = _identityModel.DriverInstanceId,
-                    ClusterId = ClusterId,
-                    Name = _identityModel.Name,
-                    DriverType = DriverTypeKey,
-                    Enabled = _identityModel.Enabled,
-                    DriverConfig = configJson,
-                    ResilienceConfig = string.IsNullOrWhiteSpace(_form.ResilienceConfig) ? null : _form.ResilienceConfig,
-                });
-            }
-            else
-            {
-                var entity = await db.DriverInstances.FirstOrDefaultAsync(
-                    d => d.ClusterId == ClusterId && d.DriverInstanceId == DriverInstanceId);
-                if (entity is null) { _error = "Row no longer exists."; return; }
-                db.Entry(entity).Property(e => e.RowVersion).OriginalValue = _form.RowVersion;
-                entity.Name = _identityModel.Name;
-                entity.Enabled = _identityModel.Enabled;
-                entity.DriverConfig = configJson;
-                entity.ResilienceConfig = string.IsNullOrWhiteSpace(_form.ResilienceConfig) ? null : _form.ResilienceConfig;
-            }
-            await db.SaveChangesAsync();
-            Nav.NavigateTo($"/clusters/{ClusterId}/drivers");
-        }
-        catch (DbUpdateConcurrencyException)
-        {
-            _error = "Another user changed this driver instance while you were editing. Reload to see the latest values, then re-apply your changes.";
-        }
-        catch (Exception ex) { _error = ex.Message; }
-        finally { _busy = false; }
-    }
-
-    private async Task DeleteAsync()
-    {
-        if (IsNew) return;
-        _busy = true; _error = null;
-        try
-        {
-            await using var db = await DbFactory.CreateDbContextAsync();
-            var entity = await db.DriverInstances.FirstOrDefaultAsync(
-                d => d.ClusterId == ClusterId && d.DriverInstanceId == DriverInstanceId);
-            if (entity is null) { Nav.NavigateTo($"/clusters/{ClusterId}/drivers"); return; }
-            db.Entry(entity).Property(e => e.RowVersion).OriginalValue = _form.RowVersion;
-            db.DriverInstances.Remove(entity);
-            await db.SaveChangesAsync();
-            Nav.NavigateTo($"/clusters/{ClusterId}/drivers");
-        }
-        catch (DbUpdateConcurrencyException)
-        {
-            _error = "Another user changed this driver instance while you were viewing it. Reload before deleting.";
-        }
-        catch (Exception ex)
-        {
-            _error = $"Delete failed: {ex.Message}. (Likely because equipment/tags still reference this driver — remove them first.)";
-        }
-        finally { _busy = false; }
-    }
-
-    private string SerializeCurrentConfig()
-        => System.Text.Json.JsonSerializer.Serialize(
-            _form.ToOptions(
-                _devices.Select(r => r.ToDefinition()).ToList()),
-            _jsonOpts);
-
-    private static AbLegacyDriverOptions? TryDeserialize(string json)
-    {
-        try { return System.Text.Json.JsonSerializer.Deserialize<AbLegacyDriverOptions>(json, _jsonOpts); }
-        catch { return null; }
-    }
-
-    // Mutable VM for the modal editor — AbLegacyDeviceOptions is an immutable record.
-    public sealed class AbLegacyDeviceRow
-    {
-        public string HostAddress { get; set; } = "";
-        public AbLegacyPlcFamily PlcFamily { get; set; } = AbLegacyPlcFamily.Slc500;
-        public string? DeviceName { get; set; }
-
-        // Original record (null for newly-added rows). Preserves fields the editor doesn't expose
-        // across a load→save.
-        private AbLegacyDeviceOptions? _source;
-
-        public AbLegacyDeviceRow Clone() => (AbLegacyDeviceRow)MemberwiseClone(); // _source is an immutable record ref — safe to share
-
-        public static AbLegacyDeviceRow FromDefinition(AbLegacyDeviceOptions d) => new()
-        {
-            HostAddress = d.HostAddress, PlcFamily = d.PlcFamily, DeviceName = d.DeviceName,
-            _source = d,
-        };
-
-        public AbLegacyDeviceOptions ToDefinition()
-        {
-            var baseDef = _source ?? new AbLegacyDeviceOptions(HostAddress.Trim(), PlcFamily);
-            return baseDef with
-            {
-                HostAddress = HostAddress.Trim(),
-                PlcFamily = PlcFamily,
-                DeviceName = string.IsNullOrWhiteSpace(DeviceName) ? null : DeviceName.Trim(),
-            };
-        }
-
-        public static string? ValidateRow(AbLegacyDeviceRow row, IReadOnlyList<AbLegacyDeviceRow> all, int? editIndex)
-        {
-            if (string.IsNullOrWhiteSpace(row.HostAddress)) return "Host address is required.";
-            for (var i = 0; i < all.Count; i++)
-                if (i != editIndex && string.Equals(all[i].HostAddress, row.HostAddress, StringComparison.OrdinalIgnoreCase))
-                    return $"Duplicate device host address '{row.HostAddress}'.";
-            return null;
-        }
-    }
-
-    // Flat mutable model — all scalar properties settable for Blazor @bind-Value.
-    // Collections (Devices, Tags) are kept on the component and passed in on ToOptions().
-    public sealed class FormModel
-    {
-        // Operation
-        public int TimeoutSeconds { get; set; } = 2;
-
-        // Probe
-        public bool ProbeEnabled { get; set; } = true;
-        public int ProbeIntervalSeconds { get; set; } = 5;
-        public int ProbeTimeoutSeconds { get; set; } = 2;
-        public string? ProbeAddress { get; set; } = "S:0";
-
-        // Admin UI probe timeout
-        public int AdminProbeTimeoutSeconds { get; set; } = 5;
-
-        // Persistence
-        public string? ResilienceConfig { get; set; }
-        public byte[] RowVersion { get; set; } = [];
-
-        public static FormModel FromOptions(AbLegacyDriverOptions o) => new()
-        {
-            TimeoutSeconds = (int)o.Timeout.TotalSeconds,
-            ProbeEnabled = o.Probe.Enabled,
-            ProbeIntervalSeconds = (int)o.Probe.Interval.TotalSeconds,
-            ProbeTimeoutSeconds = (int)o.Probe.Timeout.TotalSeconds,
-            ProbeAddress = o.Probe.ProbeAddress,
-            AdminProbeTimeoutSeconds = o.ProbeTimeoutSeconds,
-        };
-
-        public AbLegacyDriverOptions ToOptions(
-            IReadOnlyList<AbLegacyDeviceOptions> devices) => new()
-        {
-            Devices = devices,
-            Probe = new AbLegacyProbeOptions
-            {
-                Enabled = ProbeEnabled,
-                Interval = TimeSpan.FromSeconds(ProbeIntervalSeconds),
-                Timeout = TimeSpan.FromSeconds(ProbeTimeoutSeconds),
-                ProbeAddress = string.IsNullOrWhiteSpace(ProbeAddress) ? null : ProbeAddress,
-            },
-            Timeout = TimeSpan.FromSeconds(TimeoutSeconds),
-            ProbeTimeoutSeconds = AdminProbeTimeoutSeconds,
-        };
-    }
-}
@@ -1,82 +0,0 @@
-@* Dispatch page: reads DriverInstance.DriverType and dispatches to the matching typed editor
-   via <DynamicComponent> using _componentMap. Shows an error panel when the driver type has
-   no registered typed page. *@
-@page "/clusters/{ClusterId}/drivers/{DriverInstanceId}"
-@attribute [Authorize(Policy = AdminUiPolicies.ConfigEditor)]
-@rendermode RenderMode.InteractiveServer
-@using Microsoft.EntityFrameworkCore
-@using ZB.MOM.WW.OtOpcUa.Configuration
-@using ZB.MOM.WW.OtOpcUa.Configuration.Entities
-@inject IDbContextFactory<OtOpcUaConfigDbContext> DbFactory
-
-@if (!_loaded)
-{
-    <p>Loading…</p>
-}
-else if (_existing is null)
-{
-    <div class="d-flex justify-content-between align-items-center mb-3">
-        <h4 class="mb-0">Edit driver instance &middot; <span class="mono">@ClusterId</span></h4>
-        <a href="/clusters/@ClusterId/drivers" class="btn btn-outline-secondary btn-sm">Cancel</a>
-    </div>
-    <ClusterNav ClusterId="@ClusterId" ActiveTab="drivers" />
-    <section class="panel notice rise" style="animation-delay:.02s">
-        Driver instance <span class="mono">@DriverInstanceId</span> was not found in cluster <span class="mono">@ClusterId</span>.
-    </section>
-}
-else if (ResolveComponentType() is { } pageType)
-{
-    <DynamicComponent Type="pageType" Parameters="BuildParameters()" />
-}
-else
-{
-    <div class="d-flex justify-content-between align-items-center mb-3">
-        <h4 class="mb-0">Edit driver instance &middot; <span class="mono">@ClusterId</span></h4>
-        <a href="/clusters/@ClusterId/drivers" class="btn btn-outline-secondary btn-sm">Cancel</a>
-    </div>
-    <ClusterNav ClusterId="@ClusterId" ActiveTab="drivers" />
-    <section class="panel notice rise" style="animation-delay:.02s; border-color:var(--alert)">
-        Driver instance <span class="mono">@DriverInstanceId</span> has an unknown <code>DriverType</code> value of
-        <strong><span class="mono">@_existing.DriverType</span></strong>. No editor is registered for this type.
-        Likely causes: the row was written by a newer build, or the type-string was corrupted in the database.
-    </section>
-}
-
-@code {
-    [Parameter] public string ClusterId { get; set; } = "";
-    [Parameter] public string DriverInstanceId { get; set; } = "";
-
-    private DriverInstance? _existing;
-    private bool _loaded;
-
-    private static readonly IReadOnlyDictionary<string, Type> _componentMap =
-        new Dictionary<string, Type>(StringComparer.OrdinalIgnoreCase)
-        {
-            ["Modbus"]               = typeof(ModbusDriverPage),
-            ["AbCip"]                = typeof(AbCipDriverPage),
-            ["AbLegacy"]             = typeof(AbLegacyDriverPage),
-            ["S7"]                   = typeof(S7DriverPage),
-            ["TwinCat"]              = typeof(TwinCATDriverPage),
-            ["Focas"]                = typeof(FocasDriverPage),
-            ["OpcUaClient"]          = typeof(OpcUaClientDriverPage),
-            ["GalaxyMxGateway"]      = typeof(GalaxyDriverPage),
-        };
-
-    protected override async Task OnInitializedAsync()
-    {
-        await using var db = await DbFactory.CreateDbContextAsync();
-        _existing = await db.DriverInstances.AsNoTracking()
-            .FirstOrDefaultAsync(d => d.ClusterId == ClusterId && d.DriverInstanceId == DriverInstanceId);
-        _loaded = true;
-    }
-
-    private Type? ResolveComponentType()
-        => _componentMap.TryGetValue(_existing!.DriverType, out var t) ? t : null;
-
-    private IDictionary<string, object> BuildParameters()
-        => new Dictionary<string, object>
-        {
-            ["ClusterId"] = ClusterId,
-            ["DriverInstanceId"] = DriverInstanceId,
-        };
-}
@@ -1,49 +0,0 @@
-@* Driver type picker — presents a card grid of registered driver types and links to the
-   per-type new-driver creation page (/clusters/{ClusterId}/drivers/new/{slug}). *@
-@page "/clusters/{ClusterId}/drivers/new"
-@attribute [Authorize(Policy = AdminUiPolicies.ConfigEditor)]
-
-<div class="d-flex justify-content-between align-items-center mb-3">
-    <h4 class="mb-0">New driver &middot; <span class="mono">@ClusterId</span></h4>
-    <a href="/clusters/@ClusterId/drivers" class="btn btn-outline-secondary btn-sm">Cancel</a>
-</div>
-
-<ClusterNav ClusterId="@ClusterId" ActiveTab="drivers" />
-
-<section class="panel rise mt-3" style="animation-delay:.08s">
-    <div class="panel-head">Pick a driver type</div>
-    <div style="padding:1rem">
-        <div class="row g-3">
-            @foreach (var t in _types)
-            {
-                <div class="col-md-4 col-lg-3">
-                    <a href="/clusters/@ClusterId/drivers/new/@t.Slug" class="card h-100 text-decoration-none">
-                        <div class="card-body">
-                            <div class="text-muted small mono">@t.Icon</div>
-                            <div class="card-title mt-1"><strong>@t.DisplayName</strong></div>
-                            <div class="card-text small text-muted">@t.Description</div>
-                        </div>
-                    </a>
-                </div>
-            }
-        </div>
-    </div>
-</section>
-
-@code {
-    [Parameter] public string ClusterId { get; set; } = "";
-
-    private sealed record DriverTypeEntry(string DisplayName, string Slug, string Icon, string Description);
-
-    private static readonly IReadOnlyList<DriverTypeEntry> _types = new[]
-    {
-        new DriverTypeEntry("Modbus TCP",            "modbustcp",          "[M]",   "Modbus/TCP — generic registers/coils via port 502."),
-        new DriverTypeEntry("AbCip",                 "abcip",              "[CIP]", "Allen-Bradley CompactLogix/ControlLogix via CIP."),
-        new DriverTypeEntry("AbLegacy",              "ablegacy",           "[AB]",  "Allen-Bradley PLC-5/SLC-500/MicroLogix via DF1."),
-        new DriverTypeEntry("S7",                    "s7",                 "[S7]",  "Siemens S7-300/400/1200/1500 via ISO-on-TCP."),
-        new DriverTypeEntry("TwinCat",               "twincat",            "[TC]",  "Beckhoff TwinCAT via ADS."),
-        new DriverTypeEntry("Focas",                 "focas",              "[FOC]", "Fanuc CNC via FOCAS library."),
-        new DriverTypeEntry("OpcUaClient",           "opcuaclient",        "[OPC]", "Upstream OPC UA server pull."),
-        new DriverTypeEntry("Galaxy",                "galaxy",             "[Gx]",  "AVEVA System Platform (Wonderware) via mxaccessgw."),
-    };
-}
@@ -1,502 +0,0 @@
-@page "/clusters/{ClusterId}/drivers/new/focas"
-@attribute [Authorize(Policy = AdminUiPolicies.ConfigEditor)]
-@rendermode RenderMode.InteractiveServer
-@using Microsoft.AspNetCore.Components.Forms
-@using Microsoft.EntityFrameworkCore
-@using ZB.MOM.WW.OtOpcUa.AdminUI.Clients
-@using ZB.MOM.WW.OtOpcUa.AdminUI.Components.Shared.Drivers
-@using ZB.MOM.WW.OtOpcUa.AdminUI.Components.Shared.Drivers.Pickers
-@using ZB.MOM.WW.OtOpcUa.Configuration
-@using ZB.MOM.WW.OtOpcUa.Configuration.Entities
-@using ZB.MOM.WW.OtOpcUa.Driver.FOCAS
-@inject IDbContextFactory<OtOpcUaConfigDbContext> DbFactory
-@inject NavigationManager Nav
-
-<div class="d-flex justify-content-between align-items-center mb-3">
-    <h4 class="mb-0">@(IsNew ? "New Fanuc FOCAS driver" : "Edit Fanuc FOCAS driver") &middot; <span class="mono">@ClusterId</span></h4>
-    <a href="/clusters/@ClusterId/drivers" class="btn btn-outline-secondary btn-sm">Cancel</a>
-</div>
-<ClusterNav ClusterId="@ClusterId" ActiveTab="drivers" />
-
-@if (!_loaded)
-{
-    <p>Loading…</p>
-}
-else if (!IsNew && _existing is null)
-{
-    <section class="panel notice rise" style="animation-delay:.02s">
-        Driver instance <span class="mono">@DriverInstanceId</span> was not found in cluster <span class="mono">@ClusterId</span>.
-    </section>
-}
-else
-{
-    <EditForm Model="_form" OnValidSubmit="SubmitAsync" FormName="focasDriverEdit">
-        <DataAnnotationsValidator />
-        <DriverFormShell IsNew="IsNew" Busy="_busy" Error="@_error"
-                         CancelHref="@($"/clusters/{ClusterId}/drivers")"
-                         OnDelete="@(IsNew ? null : (EventCallback?)EventCallback.Factory.Create(this, DeleteAsync))">
-
-            <DriverIdentitySection Model="_identityModel" IsNew="IsNew" ShowDriverType="false" />
-
-            @if (!IsNew && !string.IsNullOrEmpty(DriverInstanceId))
-            {
-                <DriverStatusPanel DriverInstanceId="@DriverInstanceId" Enabled="@_identityModel.Enabled" />
-            }
-
-            <div class="mt-2 mb-3">
-                <DriverTestConnectButton DriverType="@DriverTypeKey"
-                                         GetConfigJson="@SerializeCurrentConfig"
-                                         TimeoutSeconds="@_form.AdminProbeTimeoutSeconds" />
-                <button type="button" class="btn btn-sm btn-outline-secondary mt-2"
-                        @onclick="@(() => _showPicker = true)">
-                    Pick address
-                </button>
-            </div>
-
-            <DriverTagPicker @bind-Visible="_showPicker"
-                             Title="FOCAS address"
-                             CurrentAddress="@_pickedAddress"
-                             OnPickAddress="@OnAddressPicked">
-                <FOCASAddressPickerBody CurrentAddress="@_pickedAddress"
-                                        CurrentAddressChanged="@((s) => _pickedAddress = s)"
-                                        GetConfigJson="@SerializeCurrentConfig" />
-            </DriverTagPicker>
-
-            @* Connection *@
-            <section class="panel rise mt-3" style="animation-delay:.05s">
-                <div class="panel-head">Connection</div>
-                <div style="padding:1rem">
-                    <div class="row">
-                        <div class="col-md-3 mb-3">
-                            <label class="form-label" for="focasTimeoutSec">Timeout (seconds)</label>
-                            <InputNumber id="focasTimeoutSec" @bind-Value="_form.TimeoutSeconds"
-                                         class="form-control form-control-sm" />
-                            <div class="form-text">Per-operation timeout. Default 2 s.</div>
-                        </div>
-                    </div>
-                </div>
-            </section>
-
-            @* Probe *@
-            <section class="panel rise mt-3" style="animation-delay:.08s">
-                <div class="panel-head">Connectivity probe</div>
-                <div style="padding:1rem">
-                    <div class="row">
-                        <div class="col-md-3 mb-3">
-                            <div class="form-check form-switch mt-2">
-                                <InputCheckbox id="focasProbeEnabled" @bind-Value="_form.ProbeEnabled"
-                                               class="form-check-input" />
-                                <label class="form-check-label" for="focasProbeEnabled">Probe enabled</label>
-                            </div>
-                        </div>
-                        <div class="col-md-3 mb-3">
-                            <label class="form-label" for="focasProbeInterval">Probe interval (s)</label>
-                            <InputNumber id="focasProbeInterval" @bind-Value="_form.ProbeIntervalSeconds"
-                                         class="form-control form-control-sm" />
-                        </div>
-                        <div class="col-md-3 mb-3">
-                            <label class="form-label" for="focasProbeTimeout">Probe timeout (s)</label>
-                            <InputNumber id="focasProbeTimeout" @bind-Value="_form.ProbeTimeoutSeconds"
-                                         class="form-control form-control-sm" />
-                        </div>
-                        <div class="col-md-3 mb-3">
-                            <label class="form-label" for="focasAdminProbe">Admin probe timeout (s)</label>
-                            <InputNumber id="focasAdminProbe" @bind-Value="_form.AdminProbeTimeoutSeconds"
-                                         class="form-control form-control-sm" />
-                            <div class="form-text">Test Connect timeout (1–60 s).</div>
-                        </div>
-                    </div>
-                </div>
-            </section>
-
-            @* Alarm projection *@
-            <section class="panel rise mt-3" style="animation-delay:.11s">
-                <div class="panel-head">Alarm projection</div>
-                <div style="padding:1rem">
-                    <div class="row">
-                        <div class="col-md-3 mb-3">
-                            <div class="form-check form-switch mt-2">
-                                <InputCheckbox id="focasAlarmEnabled" @bind-Value="_form.AlarmProjectionEnabled"
-                                               class="form-check-input" />
-                                <label class="form-check-label" for="focasAlarmEnabled">Alarm projection enabled</label>
-                            </div>
-                            <div class="form-text">Surfaces FOCAS alarms via IAlarmSource.</div>
-                        </div>
-                        <div class="col-md-3 mb-3">
-                            <label class="form-label" for="focasAlarmPoll">Alarm poll interval (s)</label>
-                            <InputNumber id="focasAlarmPoll" @bind-Value="_form.AlarmProjectionPollIntervalSeconds"
-                                         class="form-control form-control-sm" />
-                            <div class="form-text">One cnc_rdalmmsg2 call per device per tick. Default 2 s.</div>
-                        </div>
-                    </div>
-                </div>
-            </section>
-
-            @* Handle recycle *@
-            <section class="panel rise mt-3" style="animation-delay:.14s">
-                <div class="panel-head">Handle recycle</div>
-                <div style="padding:1rem">
-                    <div class="row">
-                        <div class="col-md-3 mb-3">
-                            <div class="form-check form-switch mt-2">
-                                <InputCheckbox id="focasRecycleEnabled" @bind-Value="_form.HandleRecycleEnabled"
-                                               class="form-check-input" />
-                                <label class="form-check-label" for="focasRecycleEnabled">Handle recycle enabled</label>
-                            </div>
-                            <div class="form-text">Proactive FWLIB session recycle to prevent handle pool exhaustion. Default off.</div>
-                        </div>
-                        <div class="col-md-3 mb-3">
-                            <label class="form-label" for="focasRecycleInterval">Recycle interval (minutes)</label>
-                            <InputNumber id="focasRecycleInterval" @bind-Value="_form.HandleRecycleIntervalMinutes"
-                                         class="form-control form-control-sm" />
-                            <div class="form-text">Typical: 30 min (shared pool) or 360 min (single client).</div>
-                        </div>
-                    </div>
-                </div>
-            </section>
-
-            @* Fixed tree *@
-            <section class="panel rise mt-3" style="animation-delay:.17s">
-                <div class="panel-head">Fixed-node tree</div>
-                <div style="padding:1rem">
-                    <div class="row">
-                        <div class="col-md-3 mb-3">
-                            <div class="form-check form-switch mt-2">
-                                <InputCheckbox id="focasFixedTree" @bind-Value="_form.FixedTreeEnabled"
-                                               class="form-check-input" />
-                                <label class="form-check-label" for="focasFixedTree">Fixed tree enabled</label>
-                            </div>
-                            <div class="form-text">Exposes Identity/, Axes/, etc. from cnc_sysinfo/cnc_rdaxisname/cnc_rddynamic2. Default off.</div>
-                        </div>
-                        <div class="col-md-3 mb-3">
-                            <label class="form-label" for="focasAxisPoll">Axis poll interval (ms)</label>
-                            <InputNumber id="focasAxisPoll" @bind-Value="_form.FixedTreePollIntervalMs"
-                                         class="form-control form-control-sm" />
-                            <div class="form-text">cnc_rddynamic2 cadence per axis. Default 250 ms.</div>
-                        </div>
-                        <div class="col-md-3 mb-3">
-                            <label class="form-label" for="focasProgramPoll">Program poll interval (s)</label>
-                            <InputNumber id="focasProgramPoll" @bind-Value="_form.FixedTreeProgramPollIntervalSeconds"
-                                         class="form-control form-control-sm" />
-                            <div class="form-text">Program/mode info cadence. 0 = disabled. Default 1 s.</div>
-                        </div>
-                        <div class="col-md-3 mb-3">
-                            <label class="form-label" for="focasTimerPoll">Timer poll interval (s)</label>
-                            <InputNumber id="focasTimerPoll" @bind-Value="_form.FixedTreeTimerPollIntervalSeconds"
-                                         class="form-control form-control-sm" />
-                            <div class="form-text">Power-on/cutting/cycle timer cadence. 0 = disabled. Default 30 s.</div>
-                        </div>
-                    </div>
-                </div>
-            </section>
-
-            @* Devices *@
-            <CollectionEditor TRow="FocasDeviceRow" Items="_devices" Title="Devices" ItemNoun="device"
-                              AnimationDelay=".20s"
-                              NewRow="@(() => new FocasDeviceRow())" Clone="@(r => r.Clone())"
-                              Validate="FocasDeviceRow.ValidateRow">
-                <HeaderTemplate>
-                    <tr><th>Host address</th><th>CNC series</th><th>Device name</th><th></th></tr>
-                </HeaderTemplate>
-                <RowTemplate Context="d">
-                    <td class="mono">@d.HostAddress</td><td>@d.Series</td>
-                    <td>@(string.IsNullOrWhiteSpace(d.DeviceName) ? "—" : d.DeviceName)</td>
-                </RowTemplate>
-                <EditTemplate Context="d">
-                    <div class="row g-3">
-                        <div class="col-md-6"><label class="form-label">Host address</label>
-                            <input class="form-control form-control-sm mono" @bind="d.HostAddress"
-                                   placeholder="192.168.0.10:8193" /></div>
-                        <div class="col-md-3"><label class="form-label">CNC series</label>
-                            <select class="form-select form-select-sm" @bind="d.Series">
-                                @foreach (var e in Enum.GetValues<FocasCncSeries>()) { <option value="@e">@e</option> }
-                            </select></div>
-                        <div class="col-md-3"><label class="form-label">Device name</label>
-                            <input class="form-control form-control-sm" @bind="d.DeviceName" /></div>
-                    </div>
-                </EditTemplate>
-            </CollectionEditor>
-
-            @* Tags *@
-            <section class="panel notice rise mt-3" style="animation-delay:.18s">
-                <div class="panel-head">Tags</div>
-                <div style="padding:1rem" class="text-muted">
-                    Tag authoring moves to the Raw tree (<strong>/raw</strong>) in v3 Batch 2.
-                    Pre-declared driver tags have been retired.
-                </div>
-            </section>
-
-            <DriverResilienceSection @bind-ResilienceConfig="_form.ResilienceConfig" />
-        </DriverFormShell>
-    </EditForm>
-}
-
-@code {
-    [Parameter] public string ClusterId { get; set; } = "";
-    [Parameter] public string? DriverInstanceId { get; set; }
-
-    private const string DriverTypeKey = "Focas";
-
-    private bool IsNew => string.IsNullOrEmpty(DriverInstanceId);
-
-    private static readonly System.Text.Json.JsonSerializerOptions _jsonOpts = new()
-    {
-        PropertyNamingPolicy = System.Text.Json.JsonNamingPolicy.CamelCase,
-        UnmappedMemberHandling = System.Text.Json.Serialization.JsonUnmappedMemberHandling.Skip,
-        WriteIndented = false,
-        Converters = { new System.Text.Json.Serialization.JsonStringEnumConverter() },
-    };
-
-    private FormModel _form = new();
-    private DriverIdentitySection.DriverIdentityModel _identityModel = new() { DriverType = DriverTypeKey };
-    private DriverInstance? _existing;
-    private bool _loaded, _busy;
-    private string? _error;
-
-    // Address picker state
-    private bool _showPicker;
-    private string _pickedAddress = "";
-
-    private void OnAddressPicked(string address) => _pickedAddress = address;
-
-    // Held separately because Devices/Tags are collections — edited via the CollectionEditor modal.
-    private List<FocasDeviceRow> _devices = [];
-
-    protected override async Task OnInitializedAsync()
-    {
-        await using var db = await DbFactory.CreateDbContextAsync();
-
-        if (IsNew)
-        {
-            _identityModel = new() { DriverType = DriverTypeKey, Enabled = true };
-            _form = FormModel.FromOptions(new FocasDriverOptions());
-        }
-        else
-        {
-            _existing = await db.DriverInstances.AsNoTracking()
-                .FirstOrDefaultAsync(d => d.ClusterId == ClusterId && d.DriverInstanceId == DriverInstanceId);
-            if (_existing is not null)
-            {
-                _identityModel = new()
-                {
-                    DriverInstanceId = _existing.DriverInstanceId,
-                    Name = _existing.Name,
-                    DriverType = _existing.DriverType,
-                    Enabled = _existing.Enabled,
-                };
-                var opts = TryDeserialize(_existing.DriverConfig) ?? new FocasDriverOptions();
-                _form = FormModel.FromOptions(opts);
-                _form.ResilienceConfig = _existing.ResilienceConfig;
-                _form.RowVersion = _existing.RowVersion;
-                _devices = opts.Devices.Select(FocasDeviceRow.FromDefinition).ToList();
-            }
-        }
-        _loaded = true;
-    }
-
-    private async Task SubmitAsync()
-    {
-        _busy = true; _error = null;
-        try
-        {
-            var opts = _form.ToOptions(
-                _devices.Select(r => r.ToDefinition()).ToList());
-            var configJson = System.Text.Json.JsonSerializer.Serialize(opts, _jsonOpts);
-            await using var db = await DbFactory.CreateDbContextAsync();
-            if (IsNew)
-            {
-                if (await db.DriverInstances.AnyAsync(d => d.DriverInstanceId == _identityModel.DriverInstanceId))
-                {
-                    _error = $"Driver instance '{_identityModel.DriverInstanceId}' already exists."; return;
-                }
-                db.DriverInstances.Add(new DriverInstance
-                {
-                    DriverInstanceId = _identityModel.DriverInstanceId,
-                    ClusterId = ClusterId,
-                    Name = _identityModel.Name,
-                    DriverType = DriverTypeKey,
-                    Enabled = _identityModel.Enabled,
-                    DriverConfig = configJson,
-                    ResilienceConfig = string.IsNullOrWhiteSpace(_form.ResilienceConfig) ? null : _form.ResilienceConfig,
-                });
-            }
-            else
-            {
-                var entity = await db.DriverInstances.FirstOrDefaultAsync(
-                    d => d.ClusterId == ClusterId && d.DriverInstanceId == DriverInstanceId);
-                if (entity is null) { _error = "Row no longer exists."; return; }
-                db.Entry(entity).Property(e => e.RowVersion).OriginalValue = _form.RowVersion;
-                entity.Name = _identityModel.Name;
-                entity.Enabled = _identityModel.Enabled;
-                entity.DriverConfig = configJson;
-                entity.ResilienceConfig = string.IsNullOrWhiteSpace(_form.ResilienceConfig) ? null : _form.ResilienceConfig;
-            }
-            await db.SaveChangesAsync();
-            Nav.NavigateTo($"/clusters/{ClusterId}/drivers");
-        }
-        catch (DbUpdateConcurrencyException)
-        {
-            _error = "Another user changed this driver instance while you were editing. Reload to see the latest values, then re-apply your changes.";
-        }
-        catch (Exception ex) { _error = ex.Message; }
-        finally { _busy = false; }
-    }
-
-    private async Task DeleteAsync()
-    {
-        if (IsNew) return;
-        _busy = true; _error = null;
-        try
-        {
-            await using var db = await DbFactory.CreateDbContextAsync();
-            var entity = await db.DriverInstances.FirstOrDefaultAsync(
-                d => d.ClusterId == ClusterId && d.DriverInstanceId == DriverInstanceId);
-            if (entity is null) { Nav.NavigateTo($"/clusters/{ClusterId}/drivers"); return; }
-            db.Entry(entity).Property(e => e.RowVersion).OriginalValue = _form.RowVersion;
-            db.DriverInstances.Remove(entity);
-            await db.SaveChangesAsync();
-            Nav.NavigateTo($"/clusters/{ClusterId}/drivers");
-        }
-        catch (DbUpdateConcurrencyException)
-        {
-            _error = "Another user changed this driver instance while you were viewing it. Reload before deleting.";
-        }
-        catch (Exception ex)
-        {
-            _error = $"Delete failed: {ex.Message}. (Likely because equipment/tags still reference this driver — remove them first.)";
-        }
-        finally { _busy = false; }
-    }
-
-    private string SerializeCurrentConfig()
-        => System.Text.Json.JsonSerializer.Serialize(
-            _form.ToOptions(
-                _devices.Select(r => r.ToDefinition()).ToList()),
-            _jsonOpts);
-
-    private static FocasDriverOptions? TryDeserialize(string json)
-    {
-        try { return System.Text.Json.JsonSerializer.Deserialize<FocasDriverOptions>(json, _jsonOpts); }
-        catch { return null; }
-    }
-
-    // Mutable VM for the modal editor — FocasDeviceOptions is an immutable record.
-    public sealed class FocasDeviceRow
-    {
-        public string HostAddress { get; set; } = "";
-        public FocasCncSeries Series { get; set; } = FocasCncSeries.Unknown;
-        public string? DeviceName { get; set; }
-
-        // Original record (null for newly-added rows). Preserves any fields the editor doesn't
-        // expose across a load→save.
-        private FocasDeviceOptions? _source;
-
-        public FocasDeviceRow Clone() => (FocasDeviceRow)MemberwiseClone(); // _source is an immutable record ref — safe to share
-
-        public static FocasDeviceRow FromDefinition(FocasDeviceOptions d) => new()
-        {
-            HostAddress = d.HostAddress, Series = d.Series, DeviceName = d.DeviceName,
-            _source = d,
-        };
-
-        public FocasDeviceOptions ToDefinition()
-        {
-            var baseDef = _source ?? new FocasDeviceOptions(HostAddress.Trim());
-            return baseDef with
-            {
-                HostAddress = HostAddress.Trim(),
-                Series = Series,
-                DeviceName = string.IsNullOrWhiteSpace(DeviceName) ? null : DeviceName.Trim(),
-            };
-        }
-
-        public static string? ValidateRow(FocasDeviceRow row, IReadOnlyList<FocasDeviceRow> all, int? editIndex)
-        {
-            if (string.IsNullOrWhiteSpace(row.HostAddress)) return "Host address is required.";
-            for (var i = 0; i < all.Count; i++)
-                if (i != editIndex && string.Equals(all[i].HostAddress, row.HostAddress, StringComparison.OrdinalIgnoreCase))
-                    return $"Duplicate device host address '{row.HostAddress}'.";
-            return null;
-        }
-    }
-
-    // Flat mutable model — all scalar properties settable for Blazor @bind-Value.
-    // Collections (Devices, Tags) are kept on the component and passed in on ToOptions().
-    public sealed class FormModel
-    {
-        // Connection
-        public int TimeoutSeconds { get; set; } = 2;
-
-        // Probe
-        public bool ProbeEnabled { get; set; } = true;
-        public int ProbeIntervalSeconds { get; set; } = 5;
-        public int ProbeTimeoutSeconds { get; set; } = 2;
-        public int AdminProbeTimeoutSeconds { get; set; } = 10;
-
-        // Alarm projection
-        public bool AlarmProjectionEnabled { get; set; } = false;
-        public int AlarmProjectionPollIntervalSeconds { get; set; } = 2;
-
-        // Handle recycle
-        public bool HandleRecycleEnabled { get; set; } = false;
-        public int HandleRecycleIntervalMinutes { get; set; } = 60;
-
-        // Fixed tree
-        public bool FixedTreeEnabled { get; set; } = false;
-        public int FixedTreePollIntervalMs { get; set; } = 250;
-        public int FixedTreeProgramPollIntervalSeconds { get; set; } = 1;
-        public int FixedTreeTimerPollIntervalSeconds { get; set; } = 30;
-
-        // Common
-        public string? ResilienceConfig { get; set; }
-        public byte[] RowVersion { get; set; } = [];
-
-        public static FormModel FromOptions(FocasDriverOptions o) => new()
-        {
-            TimeoutSeconds = (int)o.Timeout.TotalSeconds,
-            ProbeEnabled = o.Probe.Enabled,
-            ProbeIntervalSeconds = (int)o.Probe.Interval.TotalSeconds,
-            ProbeTimeoutSeconds = (int)o.Probe.Timeout.TotalSeconds,
-            AdminProbeTimeoutSeconds = o.ProbeTimeoutSeconds,
-            AlarmProjectionEnabled = o.AlarmProjection.Enabled,
-            AlarmProjectionPollIntervalSeconds = (int)o.AlarmProjection.PollInterval.TotalSeconds,
-            HandleRecycleEnabled = o.HandleRecycle.Enabled,
-            HandleRecycleIntervalMinutes = (int)o.HandleRecycle.Interval.TotalMinutes,
-            FixedTreeEnabled = o.FixedTree.Enabled,
-            FixedTreePollIntervalMs = (int)o.FixedTree.PollInterval.TotalMilliseconds,
-            FixedTreeProgramPollIntervalSeconds = (int)o.FixedTree.ProgramPollInterval.TotalSeconds,
-            FixedTreeTimerPollIntervalSeconds = (int)o.FixedTree.TimerPollInterval.TotalSeconds,
-        };
-
-        public FocasDriverOptions ToOptions(
-            IReadOnlyList<FocasDeviceOptions> devices) => new()
-        {
-            Timeout = TimeSpan.FromSeconds(TimeoutSeconds),
-            Probe = new FocasProbeOptions
-            {
-                Enabled = ProbeEnabled,
-                Interval = TimeSpan.FromSeconds(ProbeIntervalSeconds),
-                Timeout = TimeSpan.FromSeconds(ProbeTimeoutSeconds),
-            },
-            ProbeTimeoutSeconds = AdminProbeTimeoutSeconds,
-            AlarmProjection = new FocasAlarmProjectionOptions
-            {
-                Enabled = AlarmProjectionEnabled,
-                PollInterval = TimeSpan.FromSeconds(AlarmProjectionPollIntervalSeconds),
-            },
-            HandleRecycle = new FocasHandleRecycleOptions
-            {
-                Enabled = HandleRecycleEnabled,
-                Interval = TimeSpan.FromMinutes(HandleRecycleIntervalMinutes),
-            },
-            FixedTree = new FocasFixedTreeOptions
-            {
-                Enabled = FixedTreeEnabled,
-                PollInterval = TimeSpan.FromMilliseconds(FixedTreePollIntervalMs),
-                ProgramPollInterval = TimeSpan.FromSeconds(FixedTreeProgramPollIntervalSeconds),
-                TimerPollInterval = TimeSpan.FromSeconds(FixedTreeTimerPollIntervalSeconds),
-            },
-            Devices = devices,
-        };
-    }
-}
@@ -1,460 +0,0 @@
-@page "/clusters/{ClusterId}/drivers/new/galaxy"
-@attribute [Authorize(Policy = AdminUiPolicies.ConfigEditor)]
-@rendermode RenderMode.InteractiveServer
-@using Microsoft.AspNetCore.Components.Forms
-@using Microsoft.EntityFrameworkCore
-@using ZB.MOM.WW.OtOpcUa.AdminUI.Clients
-@using ZB.MOM.WW.OtOpcUa.AdminUI.Components.Shared.Drivers
-@using ZB.MOM.WW.OtOpcUa.AdminUI.Components.Shared.Drivers.Pickers
-@using ZB.MOM.WW.OtOpcUa.Configuration
-@using ZB.MOM.WW.OtOpcUa.Configuration.Entities
-@using ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Config
-@inject IDbContextFactory<OtOpcUaConfigDbContext> DbFactory
-@inject NavigationManager Nav
-
-<div class="d-flex justify-content-between align-items-center mb-3">
-    <h4 class="mb-0">@(IsNew ? "New AVEVA Galaxy driver" : "Edit AVEVA Galaxy driver") &middot; <span class="mono">@ClusterId</span></h4>
-    <a href="/clusters/@ClusterId/drivers" class="btn btn-outline-secondary btn-sm">Cancel</a>
-</div>
-<ClusterNav ClusterId="@ClusterId" ActiveTab="drivers" />
-
-@if (!_loaded)
-{
-    <p>Loading&hellip;</p>
-}
-else if (!IsNew && _existing is null)
-{
-    <section class="panel notice rise" style="animation-delay:.02s">
-        Driver instance <span class="mono">@DriverInstanceId</span> was not found in cluster <span class="mono">@ClusterId</span>.
-    </section>
-}
-else
-{
-    <EditForm Model="_form" OnValidSubmit="SubmitAsync" FormName="galaxyDriverEdit">
-        <DataAnnotationsValidator />
-        <DriverFormShell IsNew="IsNew" Busy="_busy" Error="@_error"
-                         CancelHref="@($"/clusters/{ClusterId}/drivers")"
-                         OnDelete="@(IsNew ? null : (EventCallback?)EventCallback.Factory.Create(this, DeleteAsync))">
-
-            <DriverIdentitySection Model="_identityModel" IsNew="IsNew" ShowDriverType="false" />
-
-            @if (!IsNew && !string.IsNullOrEmpty(DriverInstanceId))
-            {
-                <DriverStatusPanel DriverInstanceId="@DriverInstanceId" Enabled="@_identityModel.Enabled" />
-            }
-
-            <div class="mt-2 mb-3">
-                <DriverTestConnectButton DriverType="@DriverTypeKey"
-                                         GetConfigJson="@SerializeCurrentConfig"
-                                         TimeoutSeconds="@_form.Galaxy.ProbeTimeoutSeconds" />
-                <button type="button" class="btn btn-sm btn-outline-secondary mt-2"
-                        @onclick="@(() => _showPicker = true)">
-                    Pick address
-                </button>
-            </div>
-
-            <DriverTagPicker @bind-Visible="_showPicker"
-                             Title="Galaxy address"
-                             CurrentAddress="@_pickedAddress"
-                             OnPickAddress="@OnAddressPicked">
-                <GalaxyAddressPickerBody CurrentAddress="@_pickedAddress"
-                                         CurrentAddressChanged="@((s) => _pickedAddress = s)"
-                                         GetConfigJson="@SerializeCurrentConfig" />
-            </DriverTagPicker>
-
-            @* mxaccessgw connection *@
-            <section class="panel rise mt-3" style="animation-delay:.06s">
-                <div class="panel-head">mxaccessgw connection</div>
-                <div style="padding:1rem">
-                    <div class="row g-3">
-                        <div class="col-md-6">
-                            <label class="form-label">Gateway endpoint</label>
-                            <InputText @bind-Value="_form.Galaxy.GatewayEndpoint" class="form-control form-control-sm mono"
-                                       placeholder="https://localhost:5001" />
-                            <div class="form-text">gRPC endpoint of the mxaccessgw process.</div>
-                        </div>
-                        <div class="col-md-6">
-                            <label class="form-label">API key secret ref</label>
-                            <InputText @bind-Value="_form.Galaxy.GatewayApiKeySecretRef" class="form-control form-control-sm mono"
-                                       placeholder="env:MX_API_KEY" />
-                            <div class="form-text">Forms: <code>env:NAME</code>, <code>file:PATH</code>, <code>dev:KEY</code>. Cleartext is accepted but triggers a startup warning.</div>
-                        </div>
-                        <div class="col-md-3">
-                            <div class="form-check form-switch mt-4">
-                                <InputCheckbox @bind-Value="_form.Galaxy.GatewayUseTls" class="form-check-input" id="gwTls" />
-                                <label class="form-check-label" for="gwTls">Use TLS</label>
-                            </div>
-                        </div>
-                        <div class="col-md-5">
-                            <label class="form-label">CA certificate path (optional)</label>
-                            <InputText @bind-Value="_form.Galaxy.GatewayCaCertificatePath" class="form-control form-control-sm mono"
-                                       placeholder="C:\certs\ca.pem" />
-                        </div>
-                        <div class="col-md-2">
-                            <label class="form-label">Connect timeout (s)</label>
-                            <InputNumber @bind-Value="_form.Galaxy.GatewayConnectTimeoutSeconds" class="form-control form-control-sm" />
-                            <div class="form-text">Default 10 s.</div>
-                        </div>
-                        <div class="col-md-2">
-                            <label class="form-label">Call timeout (s)</label>
-                            <InputNumber @bind-Value="_form.Galaxy.GatewayDefaultCallTimeoutSeconds" class="form-control form-control-sm" />
-                            <div class="form-text">Default 30 s.</div>
-                        </div>
-                        <div class="col-md-2">
-                            <label class="form-label">Stream timeout (s, 0 = unlimited)</label>
-                            <InputNumber @bind-Value="_form.Galaxy.GatewayStreamTimeoutSeconds" class="form-control form-control-sm" />
-                            <div class="form-text">Default 0 (lifetime of driver).</div>
-                        </div>
-                    </div>
-                </div>
-            </section>
-
-            @* MXAccess *@
-            <section class="panel rise mt-3" style="animation-delay:.08s">
-                <div class="panel-head">MXAccess</div>
-                <div style="padding:1rem">
-                    <div class="row g-3">
-                        <div class="col-md-4">
-                            <label class="form-label">Client name</label>
-                            <InputText @bind-Value="_form.Galaxy.MxClientName" class="form-control form-control-sm"
-                                       placeholder="OtOpcUa-Primary" />
-                            <div class="form-text">Must be unique per OtOpcUa instance — redundancy pairs each get a distinct name.</div>
-                        </div>
-                        <div class="col-md-3">
-                            <label class="form-label">Publishing interval (ms)</label>
-                            <InputNumber @bind-Value="_form.Galaxy.MxPublishingIntervalMs" class="form-control form-control-sm" />
-                            <div class="form-text">Default 1000 ms.</div>
-                        </div>
-                        <div class="col-md-2">
-                            <label class="form-label">Write user ID</label>
-                            <InputNumber @bind-Value="_form.Galaxy.MxWriteUserId" class="form-control form-control-sm" />
-                            <div class="form-text">0 = anonymous.</div>
-                        </div>
-                        <div class="col-md-3">
-                            <label class="form-label">Event pump channel capacity</label>
-                            <InputNumber @bind-Value="_form.Galaxy.MxEventPumpChannelCapacity" class="form-control form-control-sm" />
-                            <div class="form-text">Default 50000. Raise if events.dropped appears.</div>
-                        </div>
-                    </div>
-                </div>
-            </section>
-
-            @* Repository *@
-            <section class="panel rise mt-3" style="animation-delay:.10s">
-                <div class="panel-head">Galaxy repository</div>
-                <div style="padding:1rem">
-                    <div class="row g-3">
-                        <div class="col-md-3">
-                            <label class="form-label">Discover page size</label>
-                            <InputNumber @bind-Value="_form.Galaxy.RepositoryDiscoverPageSize" class="form-control form-control-sm" />
-                            <div class="form-text">Default 5000 objects per page.</div>
-                        </div>
-                        <div class="col-md-3">
-                            <div class="form-check form-switch mt-4">
-                                <InputCheckbox @bind-Value="_form.Galaxy.RepositoryWatchDeployEvents" class="form-check-input" id="watchDeploy" />
-                                <label class="form-check-label" for="watchDeploy">Watch deploy events</label>
-                            </div>
-                            <div class="form-text mt-0">Triggers address-space rebuild on Galaxy re-deploy.</div>
-                        </div>
-                    </div>
-                </div>
-            </section>
-
-            @* Reconnect *@
-            <section class="panel rise mt-3" style="animation-delay:.12s">
-                <div class="panel-head">Reconnect backoff</div>
-                <div style="padding:1rem">
-                    <div class="row g-3">
-                        <div class="col-md-3">
-                            <label class="form-label">Initial backoff (ms)</label>
-                            <InputNumber @bind-Value="_form.Galaxy.ReconnectInitialBackoffMs" class="form-control form-control-sm" />
-                            <div class="form-text">Default 500 ms.</div>
-                        </div>
-                        <div class="col-md-3">
-                            <label class="form-label">Max backoff (ms)</label>
-                            <InputNumber @bind-Value="_form.Galaxy.ReconnectMaxBackoffMs" class="form-control form-control-sm" />
-                            <div class="form-text">Default 30000 ms.</div>
-                        </div>
-                        <div class="col-md-3">
-                            <div class="form-check form-switch mt-4">
-                                <InputCheckbox @bind-Value="_form.Galaxy.ReconnectReplayOnSessionLost" class="form-check-input" id="replayOnLost" />
-                                <label class="form-check-label" for="replayOnLost">Replay subscriptions on session lost</label>
-                            </div>
-                        </div>
-                    </div>
-                </div>
-            </section>
-
-            @* Diagnostics *@
-            <section class="panel rise mt-3" style="animation-delay:.14s">
-                <div class="panel-head">Diagnostics</div>
-                <div style="padding:1rem">
-                    <div class="row g-3">
-                        <div class="col-md-3">
-                            <label class="form-label">Admin UI probe timeout (seconds)</label>
-                            <InputNumber @bind-Value="_form.Galaxy.ProbeTimeoutSeconds" class="form-control form-control-sm" />
-                            <div class="form-text">Max 60. Used by Test Connect. Default 30.</div>
-                        </div>
-                    </div>
-                </div>
-            </section>
-
-            <DriverResilienceSection @bind-ResilienceConfig="_form.ResilienceConfig" />
-        </DriverFormShell>
-    </EditForm>
-}
-
-@code {
-    [Parameter] public string ClusterId { get; set; } = "";
-    [Parameter] public string? DriverInstanceId { get; set; }
-
-    private const string DriverTypeKey = "GalaxyMxGateway";
-
-    private bool IsNew => string.IsNullOrEmpty(DriverInstanceId);
-
-    private static readonly System.Text.Json.JsonSerializerOptions _jsonOpts = new()
-    {
-        PropertyNamingPolicy = System.Text.Json.JsonNamingPolicy.CamelCase,
-        PropertyNameCaseInsensitive = true,
-        UnmappedMemberHandling = System.Text.Json.Serialization.JsonUnmappedMemberHandling.Skip,
-        WriteIndented = false,
-        Converters = { new System.Text.Json.Serialization.JsonStringEnumConverter() },
-    };
-
-    private FormModel _form = new();
-    private DriverIdentitySection.DriverIdentityModel _identityModel = new() { DriverType = DriverTypeKey };
-    private DriverInstance? _existing;
-    private bool _loaded;
-    private bool _busy;
-    private string? _error;
-
-    // Address picker state
-    private bool _showPicker;
-    private string _pickedAddress = "";
-
-    private void OnAddressPicked(string address) => _pickedAddress = address;
-
-    protected override async Task OnInitializedAsync()
-    {
-        await using var db = await DbFactory.CreateDbContextAsync();
-
-        if (IsNew)
-        {
-            _identityModel = new()
-            {
-                DriverInstanceId = "",
-                Name = "",
-                DriverType = DriverTypeKey,
-                Enabled = true,
-            };
-            _form = new FormModel();
-        }
-        else
-        {
-            _existing = await db.DriverInstances.AsNoTracking()
-                .FirstOrDefaultAsync(d => d.ClusterId == ClusterId && d.DriverInstanceId == DriverInstanceId);
-            if (_existing is not null)
-            {
-                _identityModel = new()
-                {
-                    DriverInstanceId = _existing.DriverInstanceId,
-                    Name = _existing.Name,
-                    DriverType = _existing.DriverType,
-                    Enabled = _existing.Enabled,
-                };
-                var opts = TryDeserialize(_existing.DriverConfig) ?? CreateDefaultOptions();
-                _form = new FormModel();
-                _form.Galaxy = GalaxyFormModel.FromRecord(opts);
-                _form.ResilienceConfig = _existing.ResilienceConfig;
-                _form.RowVersion = _existing.RowVersion;
-            }
-        }
-        _loaded = true;
-    }
-
-    private static GalaxyDriverOptions CreateDefaultOptions() => new(
-        Gateway: new GalaxyGatewayOptions("https://localhost:5001", "env:MX_API_KEY"),
-        MxAccess: new GalaxyMxAccessOptions("OtOpcUa"),
-        Repository: new GalaxyRepositoryOptions(),
-        Reconnect: new GalaxyReconnectOptions());
-
-    private async Task SubmitAsync()
-    {
-        _busy = true; _error = null;
-        try
-        {
-            var opts = _form.Galaxy.ToRecord();
-            var configJson = System.Text.Json.JsonSerializer.Serialize(opts, _jsonOpts);
-            await using var db = await DbFactory.CreateDbContextAsync();
-            if (IsNew)
-            {
-                if (await db.DriverInstances.AnyAsync(d => d.DriverInstanceId == _identityModel.DriverInstanceId))
-                {
-                    _error = $"Driver instance '{_identityModel.DriverInstanceId}' already exists."; return;
-                }
-                db.DriverInstances.Add(new DriverInstance
-                {
-                    DriverInstanceId = _identityModel.DriverInstanceId,
-                    ClusterId = ClusterId,
-                    Name = _identityModel.Name,
-                    DriverType = DriverTypeKey,
-                    Enabled = _identityModel.Enabled,
-                    DriverConfig = configJson,
-                    ResilienceConfig = string.IsNullOrWhiteSpace(_form.ResilienceConfig) ? null : _form.ResilienceConfig,
-                });
-            }
-            else
-            {
-                var entity = await db.DriverInstances.FirstOrDefaultAsync(
-                    d => d.ClusterId == ClusterId && d.DriverInstanceId == DriverInstanceId);
-                if (entity is null) { _error = "Row no longer exists."; return; }
-                db.Entry(entity).Property(e => e.RowVersion).OriginalValue = _form.RowVersion;
-                entity.Name = _identityModel.Name;
-                entity.Enabled = _identityModel.Enabled;
-                entity.DriverConfig = configJson;
-                entity.ResilienceConfig = string.IsNullOrWhiteSpace(_form.ResilienceConfig) ? null : _form.ResilienceConfig;
-            }
-            await db.SaveChangesAsync();
-            Nav.NavigateTo($"/clusters/{ClusterId}/drivers");
-        }
-        catch (DbUpdateConcurrencyException)
-        {
-            _error = "Another user changed this driver instance while you were editing. Reload to see the latest values, then re-apply your changes.";
-        }
-        catch (Exception ex) { _error = ex.Message; }
-        finally { _busy = false; }
-    }
-
-    private async Task DeleteAsync()
-    {
-        if (IsNew) return;
-        _busy = true; _error = null;
-        try
-        {
-            await using var db = await DbFactory.CreateDbContextAsync();
-            var entity = await db.DriverInstances.FirstOrDefaultAsync(
-                d => d.ClusterId == ClusterId && d.DriverInstanceId == DriverInstanceId);
-            if (entity is null) { Nav.NavigateTo($"/clusters/{ClusterId}/drivers"); return; }
-            db.Entry(entity).Property(e => e.RowVersion).OriginalValue = _form.RowVersion;
-            db.DriverInstances.Remove(entity);
-            await db.SaveChangesAsync();
-            Nav.NavigateTo($"/clusters/{ClusterId}/drivers");
-        }
-        catch (DbUpdateConcurrencyException)
-        {
-            _error = "Another user changed this driver instance while you were viewing it. Reload before deleting.";
-        }
-        catch (Exception ex)
-        {
-            _error = $"Delete failed: {ex.Message}. (Likely because equipment/tags still reference this driver — remove them first.)";
-        }
-        finally { _busy = false; }
-    }
-
-    private string SerializeCurrentConfig()
-        => System.Text.Json.JsonSerializer.Serialize(_form.Galaxy.ToRecord(), _jsonOpts);
-
-    private static GalaxyDriverOptions? TryDeserialize(string json)
-    {
-        try { return System.Text.Json.JsonSerializer.Deserialize<GalaxyDriverOptions>(json, _jsonOpts); }
-        catch { return null; }
-    }
-
-    public sealed class FormModel
-    {
-        public GalaxyFormModel Galaxy { get; set; } = new();
-        public string? ResilienceConfig { get; set; }
-        public byte[] RowVersion { get; set; } = [];
-    }
-
-    /// <summary>
-    ///     Mutable flat mirror of <see cref="GalaxyDriverOptions"/> and its nested records.
-    ///     All positional-record fields are flattened with a section prefix to avoid name
-    ///     collisions. <see cref="FromRecord"/> / <see cref="ToRecord"/> handle translation.
-    /// </summary>
-    public sealed class GalaxyFormModel
-    {
-        // GalaxyGatewayOptions
-        public string GatewayEndpoint { get; set; } = "https://localhost:5001";
-        public string GatewayApiKeySecretRef { get; set; } = "env:MX_API_KEY";
-        public bool GatewayUseTls { get; set; } = true;
-        public string? GatewayCaCertificatePath { get; set; }
-        public int GatewayConnectTimeoutSeconds { get; set; } = 10;
-        public int GatewayDefaultCallTimeoutSeconds { get; set; } = 30;
-        public int GatewayStreamTimeoutSeconds { get; set; } = 0;
-
-        // GalaxyMxAccessOptions
-        public string MxClientName { get; set; } = "OtOpcUa";
-        public int MxPublishingIntervalMs { get; set; } = 1000;
-        public int MxWriteUserId { get; set; } = 0;
-        public int MxEventPumpChannelCapacity { get; set; } = 50_000;
-
-        // GalaxyRepositoryOptions
-        public int RepositoryDiscoverPageSize { get; set; } = 5000;
-        public bool RepositoryWatchDeployEvents { get; set; } = true;
-
-        // GalaxyReconnectOptions
-        public int ReconnectInitialBackoffMs { get; set; } = 500;
-        public int ReconnectMaxBackoffMs { get; set; } = 30_000;
-        public bool ReconnectReplayOnSessionLost { get; set; } = true;
-
-        // GalaxyDriverOptions top-level
-        public int ProbeTimeoutSeconds { get; set; } = 30;
-
-        public static GalaxyFormModel FromRecord(GalaxyDriverOptions r)
-        {
-            // Null-coalesce each nested record to its default so that persisted configs
-            // that pre-date a section (e.g. no Reconnect key, or PascalCase keys that
-            // don't match the camelCase deserializer) don't cause a NullReferenceException.
-            var gw   = r.Gateway    ?? new GalaxyGatewayOptions("https://localhost:5001", "env:MX_API_KEY");
-            var mx   = r.MxAccess   ?? new GalaxyMxAccessOptions("OtOpcUa");
-            var repo = r.Repository ?? new GalaxyRepositoryOptions();
-            var rc   = r.Reconnect  ?? new GalaxyReconnectOptions();
-            return new()
-            {
-                GatewayEndpoint = gw.Endpoint,
-                GatewayApiKeySecretRef = gw.ApiKeySecretRef,
-                GatewayUseTls = gw.UseTls,
-                GatewayCaCertificatePath = gw.CaCertificatePath,
-                GatewayConnectTimeoutSeconds = gw.ConnectTimeoutSeconds,
-                GatewayDefaultCallTimeoutSeconds = gw.DefaultCallTimeoutSeconds,
-                GatewayStreamTimeoutSeconds = gw.StreamTimeoutSeconds,
-                MxClientName = mx.ClientName,
-                MxPublishingIntervalMs = mx.PublishingIntervalMs,
-                MxWriteUserId = mx.WriteUserId,
-                MxEventPumpChannelCapacity = mx.EventPumpChannelCapacity,
-                RepositoryDiscoverPageSize = repo.DiscoverPageSize,
-                RepositoryWatchDeployEvents = repo.WatchDeployEvents,
-                ReconnectInitialBackoffMs = rc.InitialBackoffMs,
-                ReconnectMaxBackoffMs = rc.MaxBackoffMs,
-                ReconnectReplayOnSessionLost = rc.ReplayOnSessionLost,
-                ProbeTimeoutSeconds = r.ProbeTimeoutSeconds,
-            };
-        }
-
-        public GalaxyDriverOptions ToRecord() => new(
-            Gateway: new GalaxyGatewayOptions(
-                Endpoint: GatewayEndpoint,
-                ApiKeySecretRef: GatewayApiKeySecretRef,
-                UseTls: GatewayUseTls,
-                CaCertificatePath: string.IsNullOrWhiteSpace(GatewayCaCertificatePath) ? null : GatewayCaCertificatePath,
-                ConnectTimeoutSeconds: GatewayConnectTimeoutSeconds,
-                DefaultCallTimeoutSeconds: GatewayDefaultCallTimeoutSeconds,
-                StreamTimeoutSeconds: GatewayStreamTimeoutSeconds),
-            MxAccess: new GalaxyMxAccessOptions(
-                ClientName: MxClientName,
-                PublishingIntervalMs: MxPublishingIntervalMs,
-                WriteUserId: MxWriteUserId,
-                EventPumpChannelCapacity: MxEventPumpChannelCapacity),
-            Repository: new GalaxyRepositoryOptions(
-                DiscoverPageSize: RepositoryDiscoverPageSize,
-                WatchDeployEvents: RepositoryWatchDeployEvents),
-            Reconnect: new GalaxyReconnectOptions(
-                InitialBackoffMs: ReconnectInitialBackoffMs,
-                MaxBackoffMs: ReconnectMaxBackoffMs,
-                ReplayOnSessionLost: ReconnectReplayOnSessionLost))
-        {
-            ProbeTimeoutSeconds = ProbeTimeoutSeconds,
-        };
-    }
-}
@@ -1,572 +0,0 @@
-@page "/clusters/{ClusterId}/drivers/new/modbustcp"
-@attribute [Authorize(Policy = AdminUiPolicies.ConfigEditor)]
-@rendermode RenderMode.InteractiveServer
-@using Microsoft.AspNetCore.Components.Forms
-@using Microsoft.EntityFrameworkCore
-@using ZB.MOM.WW.OtOpcUa.AdminUI.Clients
-@using ZB.MOM.WW.OtOpcUa.AdminUI.Components.Shared.Drivers
-@using ZB.MOM.WW.OtOpcUa.AdminUI.Components.Shared.Drivers.Pickers
-@using ZB.MOM.WW.OtOpcUa.Configuration
-@using ZB.MOM.WW.OtOpcUa.Configuration.Entities
-@using ZB.MOM.WW.OtOpcUa.Driver.Modbus
-@inject IDbContextFactory<OtOpcUaConfigDbContext> DbFactory
-@inject NavigationManager Nav
-
-<div class="d-flex justify-content-between align-items-center mb-3">
-    <h4 class="mb-0">@(IsNew ? "New Modbus/TCP driver" : "Edit Modbus/TCP driver") &middot; <span class="mono">@ClusterId</span></h4>
-    <a href="/clusters/@ClusterId/drivers" class="btn btn-outline-secondary btn-sm">Cancel</a>
-</div>
-<ClusterNav ClusterId="@ClusterId" ActiveTab="drivers" />
-
-@if (!_loaded)
-{
-    <p>Loading&hellip;</p>
-}
-else if (!IsNew && _existing is null)
-{
-    <section class="panel notice rise" style="animation-delay:.02s">
-        Driver instance <span class="mono">@DriverInstanceId</span> was not found in cluster <span class="mono">@ClusterId</span>.
-    </section>
-}
-else
-{
-    <EditForm Model="_form" OnValidSubmit="SubmitAsync" FormName="modbustcpDriverEdit">
-        <DataAnnotationsValidator />
-        <DriverFormShell IsNew="IsNew" Busy="_busy" Error="@_error"
-                         CancelHref="@($"/clusters/{ClusterId}/drivers")"
-                         OnDelete="@(IsNew ? null : (EventCallback?)EventCallback.Factory.Create(this, DeleteAsync))">
-
-            <DriverIdentitySection Model="_identityModel" IsNew="IsNew" ShowDriverType="false" />
-
-            @if (!IsNew && !string.IsNullOrEmpty(DriverInstanceId))
-            {
-                <DriverStatusPanel DriverInstanceId="@DriverInstanceId" Enabled="@_identityModel.Enabled" />
-            }
-
-            <div class="mt-2 mb-3">
-                <DriverTestConnectButton DriverType="@DriverTypeKey"
-                                         GetConfigJson="@SerializeCurrentConfig"
-                                         TimeoutSeconds="@_form.AdminProbeTimeoutSeconds" />
-                <button type="button" class="btn btn-sm btn-outline-secondary mt-2"
-                        @onclick="@(() => _showPicker = true)">
-                    Pick address
-                </button>
-            </div>
-
-            <DriverTagPicker @bind-Visible="_showPicker"
-                             Title="Modbus address"
-                             CurrentAddress="@_pickedAddress"
-                             OnPickAddress="@OnAddressPicked">
-                <ModbusAddressPickerBody CurrentAddress="@_pickedAddress"
-                                         CurrentAddressChanged="@((s) => _pickedAddress = s)" />
-            </DriverTagPicker>
-
-            @* Transport *@
-            <section class="panel rise mt-3" style="animation-delay:.06s">
-                <div class="panel-head">Transport</div>
-                <div style="padding:1rem">
-                    <div class="row g-3">
-                        <div class="col-md-6">
-                            <label class="form-label">Host</label>
-                            <InputText @bind-Value="_form.Host" class="form-control form-control-sm" placeholder="127.0.0.1" />
-                        </div>
-                        <div class="col-md-3">
-                            <label class="form-label">Port</label>
-                            <InputNumber @bind-Value="_form.Port" class="form-control form-control-sm" />
-                        </div>
-                        <div class="col-md-3">
-                            <label class="form-label">Unit ID (slave ID)</label>
-                            <InputNumber @bind-Value="_form.UnitId" class="form-control form-control-sm" />
-                        </div>
-                        <div class="col-md-3">
-                            <label class="form-label">Timeout (seconds)</label>
-                            <InputNumber @bind-Value="_form.TimeoutSeconds" class="form-control form-control-sm" />
-                            <div class="form-text">Default 2 s.</div>
-                        </div>
-                        <div class="col-md-3">
-                            <label class="form-label">PLC family</label>
-                            <InputSelect @bind-Value="_form.Family" class="form-select form-select-sm">
-                                @foreach (var e in Enum.GetValues<ModbusFamily>())
-                                {
-                                    <option value="@e">@e</option>
-                                }
-                            </InputSelect>
-                        </div>
-                        <div class="col-md-3">
-                            <label class="form-label">MELSEC sub-family</label>
-                            <InputSelect @bind-Value="_form.MelsecSubFamily" class="form-select form-select-sm">
-                                @foreach (var e in Enum.GetValues<MelsecFamily>())
-                                {
-                                    <option value="@e">@e</option>
-                                }
-                            </InputSelect>
-                            <div class="form-text">Only used when Family = MELSEC.</div>
-                        </div>
-                        <div class="col-md-3">
-                            <div class="form-check form-switch mt-4">
-                                <InputCheckbox @bind-Value="_form.AutoReconnect" class="form-check-input" id="autoReconnect" />
-                                <label class="form-check-label" for="autoReconnect">Auto-reconnect</label>
-                            </div>
-                        </div>
-                    </div>
-                </div>
-            </section>
-
-            @* Batch sizes *@
-            <section class="panel rise mt-3" style="animation-delay:.08s">
-                <div class="panel-head">Batch sizes</div>
-                <div style="padding:1rem">
-                    <div class="row g-3">
-                        <div class="col-md-3">
-                            <label class="form-label">Max registers per read</label>
-                            <InputNumber @bind-Value="_form.MaxRegistersPerRead" class="form-control form-control-sm" />
-                            <div class="form-text">Spec max 125. Reduce for limited devices.</div>
-                        </div>
-                        <div class="col-md-3">
-                            <label class="form-label">Max registers per write</label>
-                            <InputNumber @bind-Value="_form.MaxRegistersPerWrite" class="form-control form-control-sm" />
-                            <div class="form-text">Spec max 123.</div>
-                        </div>
-                        <div class="col-md-3">
-                            <label class="form-label">Max coils per read</label>
-                            <InputNumber @bind-Value="_form.MaxCoilsPerRead" class="form-control form-control-sm" />
-                            <div class="form-text">Spec max 2000.</div>
-                        </div>
-                        <div class="col-md-3">
-                            <label class="form-label">Max read gap (coalescing)</label>
-                            <InputNumber @bind-Value="_form.MaxReadGap" class="form-control form-control-sm" />
-                            <div class="form-text">0 = no coalescing. Typical 5–32.</div>
-                        </div>
-                    </div>
-                </div>
-            </section>
-
-            @* Write options *@
-            <section class="panel rise mt-3" style="animation-delay:.10s">
-                <div class="panel-head">Write options</div>
-                <div style="padding:1rem">
-                    <div class="row g-3">
-                        <div class="col-md-4">
-                            <div class="form-check form-switch">
-                                <InputCheckbox @bind-Value="_form.UseFC15ForSingleCoilWrites" class="form-check-input" id="useFC15" />
-                                <label class="form-check-label" for="useFC15">Use FC15 for single coil writes</label>
-                            </div>
-                        </div>
-                        <div class="col-md-4">
-                            <div class="form-check form-switch">
-                                <InputCheckbox @bind-Value="_form.UseFC16ForSingleRegisterWrites" class="form-check-input" id="useFC16" />
-                                <label class="form-check-label" for="useFC16">Use FC16 for single register writes</label>
-                            </div>
-                        </div>
-                        <div class="col-md-4">
-                            <div class="form-check form-switch">
-                                <InputCheckbox @bind-Value="_form.DisableFC23" class="form-check-input" id="disableFC23" />
-                                <label class="form-check-label" for="disableFC23">Disable FC23 (reserved — no effect today)</label>
-                            </div>
-                        </div>
-                        <div class="col-md-4">
-                            <div class="form-check form-switch">
-                                <InputCheckbox @bind-Value="_form.WriteOnChangeOnly" class="form-check-input" id="writeOnChangeOnly" />
-                                <label class="form-check-label" for="writeOnChangeOnly">Write on change only</label>
-                            </div>
-                        </div>
-                    </div>
-                </div>
-            </section>
-
-            @* Keep-alive *@
-            <section class="panel rise mt-3" style="animation-delay:.12s">
-                <div class="panel-head">TCP keep-alive</div>
-                <div style="padding:1rem">
-                    <div class="row g-3">
-                        <div class="col-md-3">
-                            <div class="form-check form-switch mt-4">
-                                <InputCheckbox @bind-Value="_form.KeepAliveEnabled" class="form-check-input" id="kaEnabled" />
-                                <label class="form-check-label" for="kaEnabled">Enabled</label>
-                            </div>
-                        </div>
-                        <div class="col-md-3">
-                            <label class="form-label">Time (seconds)</label>
-                            <InputNumber @bind-Value="_form.KeepAliveTimeSeconds" class="form-control form-control-sm" />
-                            <div class="form-text">Idle time before first probe. Default 30 s.</div>
-                        </div>
-                        <div class="col-md-3">
-                            <label class="form-label">Interval (seconds)</label>
-                            <InputNumber @bind-Value="_form.KeepAliveIntervalSeconds" class="form-control form-control-sm" />
-                            <div class="form-text">Between probes once started. Default 10 s.</div>
-                        </div>
-                        <div class="col-md-3">
-                            <label class="form-label">Retry count</label>
-                            <InputNumber @bind-Value="_form.KeepAliveRetryCount" class="form-control form-control-sm" />
-                            <div class="form-text">Probes before declaring socket dead. Default 3.</div>
-                        </div>
-                    </div>
-                </div>
-            </section>
-
-            @* Reconnect backoff *@
-            <section class="panel rise mt-3" style="animation-delay:.14s">
-                <div class="panel-head">Reconnect backoff</div>
-                <div style="padding:1rem">
-                    <div class="row g-3">
-                        <div class="col-md-3">
-                            <label class="form-label">Initial delay (seconds)</label>
-                            <InputNumber @bind-Value="_form.ReconnectInitialDelaySeconds" class="form-control form-control-sm" />
-                            <div class="form-text">0 = immediate retry.</div>
-                        </div>
-                        <div class="col-md-3">
-                            <label class="form-label">Max delay (seconds)</label>
-                            <InputNumber @bind-Value="_form.ReconnectMaxDelaySeconds" class="form-control form-control-sm" />
-                            <div class="form-text">Default 30 s.</div>
-                        </div>
-                        <div class="col-md-3">
-                            <label class="form-label">Backoff multiplier</label>
-                            <InputNumber @bind-Value="_form.ReconnectBackoffMultiplier" class="form-control form-control-sm" />
-                            <div class="form-text">Default 2.0 (doubles each step).</div>
-                        </div>
-                        <div class="col-md-3">
-                            <label class="form-label">Idle disconnect (seconds, 0 = off)</label>
-                            <InputNumber @bind-Value="_form.IdleDisconnectTimeoutSeconds" class="form-control form-control-sm" />
-                            <div class="form-text">Proactive close after idle period. 0 = disabled.</div>
-                        </div>
-                    </div>
-                </div>
-            </section>
-
-            @* Probe *@
-            <section class="panel rise mt-3" style="animation-delay:.16s">
-                <div class="panel-head">Connectivity probe</div>
-                <div style="padding:1rem">
-                    <div class="row g-3">
-                        <div class="col-md-3">
-                            <div class="form-check form-switch mt-4">
-                                <InputCheckbox @bind-Value="_form.ProbeEnabled" class="form-check-input" id="probeEnabled" />
-                                <label class="form-check-label" for="probeEnabled">Enabled</label>
-                            </div>
-                        </div>
-                        <div class="col-md-3">
-                            <label class="form-label">Probe interval (seconds)</label>
-                            <InputNumber @bind-Value="_form.ProbeIntervalSeconds" class="form-control form-control-sm" />
-                            <div class="form-text">Default 5 s.</div>
-                        </div>
-                        <div class="col-md-3">
-                            <label class="form-label">Probe timeout (seconds)</label>
-                            <InputNumber @bind-Value="_form.ProbeTimeoutSeconds" class="form-control form-control-sm" />
-                            <div class="form-text">Default 2 s.</div>
-                        </div>
-                        <div class="col-md-3">
-                            <label class="form-label">Probe register address</label>
-                            <InputNumber @bind-Value="_form.ProbeAddress" class="form-control form-control-sm" />
-                            <div class="form-text">Zero-based. Default 0 (FC03 at register 0).</div>
-                        </div>
-                        <div class="col-md-3">
-                            <label class="form-label">Admin UI probe timeout (seconds)</label>
-                            <InputNumber @bind-Value="_form.AdminProbeTimeoutSeconds" class="form-control form-control-sm" />
-                            <div class="form-text">Max 60. Used by Test Connect. Default 5.</div>
-                        </div>
-                        <div class="col-md-3">
-                            <label class="form-label">Auto-prohibit re-probe interval (seconds, 0 = off)</label>
-                            <InputNumber @bind-Value="_form.AutoProhibitReprobeIntervalSeconds" class="form-control form-control-sm" />
-                            <div class="form-text">Interval to retry auto-prohibited coalesced ranges.</div>
-                        </div>
-                    </div>
-                </div>
-            </section>
-
-            <section class="panel notice rise mt-3" style="animation-delay:.18s">
-                <div class="panel-head">Tags</div>
-                <div style="padding:1rem" class="text-muted">
-                    Tag authoring moves to the Raw tree (<strong>/raw</strong>) in v3 Batch 2.
-                    Pre-declared driver tags have been retired.
-                </div>
-            </section>
-
-            <DriverResilienceSection @bind-ResilienceConfig="_form.ResilienceConfig" />
-        </DriverFormShell>
-    </EditForm>
-}
-
-@code {
-    [Parameter] public string ClusterId { get; set; } = "";
-    [Parameter] public string? DriverInstanceId { get; set; }
-
-    private const string DriverTypeKey = "Modbus";
-
-    private bool IsNew => string.IsNullOrEmpty(DriverInstanceId);
-
-    private static readonly System.Text.Json.JsonSerializerOptions _jsonOpts = new()
-    {
-        PropertyNamingPolicy = System.Text.Json.JsonNamingPolicy.CamelCase,
-        UnmappedMemberHandling = System.Text.Json.Serialization.JsonUnmappedMemberHandling.Skip,
-        WriteIndented = false,
-        Converters = { new System.Text.Json.Serialization.JsonStringEnumConverter() },
-    };
-
-    private FormModel _form = new();
-    private DriverIdentitySection.DriverIdentityModel _identityModel = new() { DriverType = DriverTypeKey };
-    private DriverInstance? _existing;
-    private bool _loaded;
-    private bool _busy;
-    private string? _error;
-
-    // Address picker state
-    private bool _showPicker;
-    private string _pickedAddress = "";
-
-    private void OnAddressPicked(string address) => _pickedAddress = address;
-
-    protected override async Task OnInitializedAsync()
-    {
-        await using var db = await DbFactory.CreateDbContextAsync();
-
-        if (IsNew)
-        {
-            _identityModel = new()
-            {
-                DriverInstanceId = "",
-                Name = "",
-                DriverType = DriverTypeKey,
-                Enabled = true,
-            };
-            _form = new FormModel();
-        }
-        else
-        {
-            _existing = await db.DriverInstances.AsNoTracking()
-                .FirstOrDefaultAsync(d => d.ClusterId == ClusterId && d.DriverInstanceId == DriverInstanceId);
-            if (_existing is not null)
-            {
-                _identityModel = new()
-                {
-                    DriverInstanceId = _existing.DriverInstanceId,
-                    Name = _existing.Name,
-                    DriverType = _existing.DriverType,
-                    Enabled = _existing.Enabled,
-                };
-                var opts = TryDeserialize(_existing.DriverConfig) ?? new ModbusDriverOptions();
-                _form = FormModel.FromOptions(opts);
-                _form.ResilienceConfig = _existing.ResilienceConfig;
-                _form.RowVersion = _existing.RowVersion;
-            }
-        }
-        _loaded = true;
-    }
-
-    private async Task SubmitAsync()
-    {
-        _busy = true; _error = null;
-        try
-        {
-            var configJson = System.Text.Json.JsonSerializer.Serialize(_form.ToOptions(), _jsonOpts);
-            await using var db = await DbFactory.CreateDbContextAsync();
-            if (IsNew)
-            {
-                if (await db.DriverInstances.AnyAsync(d => d.DriverInstanceId == _identityModel.DriverInstanceId))
-                {
-                    _error = $"Driver instance '{_identityModel.DriverInstanceId}' already exists.";
-                    return;
-                }
-                db.DriverInstances.Add(new DriverInstance
-                {
-                    DriverInstanceId = _identityModel.DriverInstanceId,
-                    ClusterId = ClusterId,
-                    Name = _identityModel.Name,
-                    DriverType = DriverTypeKey,
-                    Enabled = _identityModel.Enabled,
-                    DriverConfig = configJson,
-                    ResilienceConfig = string.IsNullOrWhiteSpace(_form.ResilienceConfig) ? null : _form.ResilienceConfig,
-                });
-            }
-            else
-            {
-                var entity = await db.DriverInstances.FirstOrDefaultAsync(
-                    d => d.ClusterId == ClusterId && d.DriverInstanceId == DriverInstanceId);
-                if (entity is null) { _error = "Row no longer exists."; return; }
-                db.Entry(entity).Property(e => e.RowVersion).OriginalValue = _form.RowVersion;
-                entity.Name = _identityModel.Name;
-                entity.Enabled = _identityModel.Enabled;
-                entity.DriverConfig = configJson;
-                entity.ResilienceConfig = string.IsNullOrWhiteSpace(_form.ResilienceConfig) ? null : _form.ResilienceConfig;
-            }
-            await db.SaveChangesAsync();
-            Nav.NavigateTo($"/clusters/{ClusterId}/drivers");
-        }
-        catch (DbUpdateConcurrencyException)
-        {
-            _error = "Another user changed this driver instance while you were editing. Reload to see the latest values, then re-apply your changes.";
-        }
-        catch (Exception ex) { _error = ex.Message; }
-        finally { _busy = false; }
-    }
-
-    private async Task DeleteAsync()
-    {
-        if (IsNew) return;
-        _busy = true; _error = null;
-        try
-        {
-            await using var db = await DbFactory.CreateDbContextAsync();
-            var entity = await db.DriverInstances.FirstOrDefaultAsync(
-                d => d.ClusterId == ClusterId && d.DriverInstanceId == DriverInstanceId);
-            if (entity is null) { Nav.NavigateTo($"/clusters/{ClusterId}/drivers"); return; }
-            db.Entry(entity).Property(e => e.RowVersion).OriginalValue = _form.RowVersion;
-            db.DriverInstances.Remove(entity);
-            await db.SaveChangesAsync();
-            Nav.NavigateTo($"/clusters/{ClusterId}/drivers");
-        }
-        catch (DbUpdateConcurrencyException)
-        {
-            _error = "Another user changed this driver instance while you were viewing it. Reload before deleting.";
-        }
-        catch (Exception ex)
-        {
-            _error = $"Delete failed: {ex.Message}. (Likely because equipment/tags still reference this driver — remove them first.)";
-        }
-        finally { _busy = false; }
-    }
-
-    private string SerializeCurrentConfig()
-        => System.Text.Json.JsonSerializer.Serialize(_form.ToOptions(), _jsonOpts);
-
-    private static ModbusDriverOptions? TryDeserialize(string json)
-    {
-        try { return System.Text.Json.JsonSerializer.Deserialize<ModbusDriverOptions>(json, _jsonOpts); }
-        catch { return null; }
-    }
-
-    // Flat mutable model — all scalars exposed as settable properties so Blazor @bind-Value works.
-    // Collection (Tags) is kept on the component (_tags) and passed in when building the final Options.
-    public sealed class FormModel
-    {
-        // Transport
-        public string Host { get; set; } = "127.0.0.1";
-        public int Port { get; set; } = 502;
-        public int UnitId { get; set; } = 1;
-        public int TimeoutSeconds { get; set; } = 2;
-
-        // Family
-        public ModbusFamily Family { get; set; } = ModbusFamily.Generic;
-        public MelsecFamily MelsecSubFamily { get; set; } = MelsecFamily.Q_L_iQR;
-
-        // Transport flags
-        public bool AutoReconnect { get; set; } = true;
-        public int IdleDisconnectTimeoutSeconds { get; set; } = 0;
-
-        // Batch sizes (using int; clamped to ushort on ToOptions)
-        public int MaxRegistersPerRead { get; set; } = 125;
-        public int MaxRegistersPerWrite { get; set; } = 123;
-        public int MaxCoilsPerRead { get; set; } = 2000;
-        public int MaxReadGap { get; set; } = 0;
-
-        // Write options
-        public bool UseFC15ForSingleCoilWrites { get; set; } = false;
-        public bool UseFC16ForSingleRegisterWrites { get; set; } = false;
-        public bool DisableFC23 { get; set; } = false;
-        public bool WriteOnChangeOnly { get; set; } = false;
-
-        // Keep-alive
-        public bool KeepAliveEnabled { get; set; } = true;
-        public int KeepAliveTimeSeconds { get; set; } = 30;
-        public int KeepAliveIntervalSeconds { get; set; } = 10;
-        public int KeepAliveRetryCount { get; set; } = 3;
-
-        // Reconnect backoff
-        public int ReconnectInitialDelaySeconds { get; set; } = 0;
-        public int ReconnectMaxDelaySeconds { get; set; } = 30;
-        public double ReconnectBackoffMultiplier { get; set; } = 2.0;
-
-        // Probe
-        public bool ProbeEnabled { get; set; } = true;
-        public int ProbeIntervalSeconds { get; set; } = 5;
-        public int ProbeTimeoutSeconds { get; set; } = 2;
-        public int ProbeAddress { get; set; } = 0;
-
-        // Auto-prohibit re-probe (0 = disabled)
-        public int AutoProhibitReprobeIntervalSeconds { get; set; } = 0;
-
-        // Admin UI probe timeout
-        public int AdminProbeTimeoutSeconds { get; set; } = 5;
-
-        // Persistence
-        public string? ResilienceConfig { get; set; }
-        public byte[] RowVersion { get; set; } = [];
-
-        public static FormModel FromOptions(ModbusDriverOptions o) => new()
-        {
-            Host = o.Host,
-            Port = o.Port,
-            UnitId = o.UnitId,
-            TimeoutSeconds = (int)o.Timeout.TotalSeconds,
-            Family = o.Family,
-            MelsecSubFamily = o.MelsecSubFamily,
-            AutoReconnect = o.AutoReconnect,
-            IdleDisconnectTimeoutSeconds = o.IdleDisconnectTimeout.HasValue ? (int)o.IdleDisconnectTimeout.Value.TotalSeconds : 0,
-            MaxRegistersPerRead = o.MaxRegistersPerRead,
-            MaxRegistersPerWrite = o.MaxRegistersPerWrite,
-            MaxCoilsPerRead = o.MaxCoilsPerRead,
-            MaxReadGap = o.MaxReadGap,
-            UseFC15ForSingleCoilWrites = o.UseFC15ForSingleCoilWrites,
-            UseFC16ForSingleRegisterWrites = o.UseFC16ForSingleRegisterWrites,
-            DisableFC23 = o.DisableFC23,
-            WriteOnChangeOnly = o.WriteOnChangeOnly,
-            KeepAliveEnabled = o.KeepAlive.Enabled,
-            KeepAliveTimeSeconds = (int)o.KeepAlive.Time.TotalSeconds,
-            KeepAliveIntervalSeconds = (int)o.KeepAlive.Interval.TotalSeconds,
-            KeepAliveRetryCount = o.KeepAlive.RetryCount,
-            ReconnectInitialDelaySeconds = (int)o.Reconnect.InitialDelay.TotalSeconds,
-            ReconnectMaxDelaySeconds = (int)o.Reconnect.MaxDelay.TotalSeconds,
-            ReconnectBackoffMultiplier = o.Reconnect.BackoffMultiplier,
-            ProbeEnabled = o.Probe.Enabled,
-            ProbeIntervalSeconds = (int)o.Probe.Interval.TotalSeconds,
-            ProbeTimeoutSeconds = (int)o.Probe.Timeout.TotalSeconds,
-            ProbeAddress = o.Probe.ProbeAddress,
-            AutoProhibitReprobeIntervalSeconds = o.AutoProhibitReprobeInterval.HasValue
-                ? (int)o.AutoProhibitReprobeInterval.Value.TotalSeconds : 0,
-            AdminProbeTimeoutSeconds = o.ProbeTimeoutSeconds,
-        };
-
-        public ModbusDriverOptions ToOptions() => new()
-        {
-            Host = Host,
-            Port = Port,
-            UnitId = (byte)Math.Clamp(UnitId, 0, 255),
-            Timeout = TimeSpan.FromSeconds(TimeoutSeconds),
-            Probe = new ModbusProbeOptions
-            {
-                Enabled = ProbeEnabled,
-                Interval = TimeSpan.FromSeconds(ProbeIntervalSeconds),
-                Timeout = TimeSpan.FromSeconds(ProbeTimeoutSeconds),
-                ProbeAddress = (ushort)Math.Clamp(ProbeAddress, 0, 65535),
-            },
-            MaxRegistersPerRead = (ushort)Math.Clamp(MaxRegistersPerRead, 0, 65535),
-            MaxRegistersPerWrite = (ushort)Math.Clamp(MaxRegistersPerWrite, 0, 65535),
-            MaxCoilsPerRead = (ushort)Math.Clamp(MaxCoilsPerRead, 0, 65535),
-            UseFC15ForSingleCoilWrites = UseFC15ForSingleCoilWrites,
-            UseFC16ForSingleRegisterWrites = UseFC16ForSingleRegisterWrites,
-            DisableFC23 = DisableFC23,
-            AutoProhibitReprobeInterval = AutoProhibitReprobeIntervalSeconds > 0
-                ? TimeSpan.FromSeconds(AutoProhibitReprobeIntervalSeconds) : null,
-            MaxReadGap = (ushort)Math.Clamp(MaxReadGap, 0, 65535),
-            Family = Family,
-            MelsecSubFamily = MelsecSubFamily,
-            WriteOnChangeOnly = WriteOnChangeOnly,
-            AutoReconnect = AutoReconnect,
-            KeepAlive = new ModbusKeepAliveOptions
-            {
-                Enabled = KeepAliveEnabled,
-                Time = TimeSpan.FromSeconds(KeepAliveTimeSeconds),
-                Interval = TimeSpan.FromSeconds(KeepAliveIntervalSeconds),
-                RetryCount = KeepAliveRetryCount,
-            },
-            IdleDisconnectTimeout = IdleDisconnectTimeoutSeconds > 0
-                ? TimeSpan.FromSeconds(IdleDisconnectTimeoutSeconds) : null,
-            Reconnect = new ModbusReconnectOptions
-            {
-                InitialDelay = TimeSpan.FromSeconds(ReconnectInitialDelaySeconds),
-                MaxDelay = TimeSpan.FromSeconds(ReconnectMaxDelaySeconds),
-                BackoffMultiplier = ReconnectBackoffMultiplier,
-            },
-            ProbeTimeoutSeconds = AdminProbeTimeoutSeconds,
-        };
-    }
-}
@@ -1,554 +0,0 @@
-@page "/clusters/{ClusterId}/drivers/new/opcuaclient"
-@attribute [Authorize(Policy = AdminUiPolicies.ConfigEditor)]
-@rendermode RenderMode.InteractiveServer
-@using Microsoft.AspNetCore.Components.Forms
-@using Microsoft.EntityFrameworkCore
-@using ZB.MOM.WW.OtOpcUa.AdminUI.Clients
-@using ZB.MOM.WW.OtOpcUa.AdminUI.Components.Shared.Drivers
-@using ZB.MOM.WW.OtOpcUa.AdminUI.Components.Shared.Drivers.Pickers
-@using ZB.MOM.WW.OtOpcUa.Configuration
-@using ZB.MOM.WW.OtOpcUa.Configuration.Entities
-@using ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient
-@inject IDbContextFactory<OtOpcUaConfigDbContext> DbFactory
-@inject NavigationManager Nav
-
-<div class="d-flex justify-content-between align-items-center mb-3">
-    <h4 class="mb-0">@(IsNew ? "New OPC UA Client driver" : "Edit OPC UA Client driver") &middot; <span class="mono">@ClusterId</span></h4>
-    <a href="/clusters/@ClusterId/drivers" class="btn btn-outline-secondary btn-sm">Cancel</a>
-</div>
-<ClusterNav ClusterId="@ClusterId" ActiveTab="drivers" />
-
-@if (!_loaded)
-{
-    <p>Loading&hellip;</p>
-}
-else if (!IsNew && _existing is null)
-{
-    <section class="panel notice rise" style="animation-delay:.02s">
-        Driver instance <span class="mono">@DriverInstanceId</span> was not found in cluster <span class="mono">@ClusterId</span>.
-    </section>
-}
-else
-{
-    <EditForm Model="_form" OnValidSubmit="SubmitAsync" FormName="opcuaclientDriverEdit">
-        <DataAnnotationsValidator />
-        <DriverFormShell IsNew="IsNew" Busy="_busy" Error="@_error"
-                         CancelHref="@($"/clusters/{ClusterId}/drivers")"
-                         OnDelete="@(IsNew ? null : (EventCallback?)EventCallback.Factory.Create(this, DeleteAsync))">
-
-            <DriverIdentitySection Model="_identityModel" IsNew="IsNew" ShowDriverType="false" />
-
-            @if (!IsNew && !string.IsNullOrEmpty(DriverInstanceId))
-            {
-                <DriverStatusPanel DriverInstanceId="@DriverInstanceId" Enabled="@_identityModel.Enabled" />
-            }
-
-            <div class="mt-2 mb-3">
-                <DriverTestConnectButton DriverType="@DriverTypeKey"
-                                         GetConfigJson="@SerializeCurrentConfig"
-                                         TimeoutSeconds="@_form.OpcUa.ProbeTimeoutSeconds" />
-                <button type="button" class="btn btn-sm btn-outline-secondary mt-2"
-                        @onclick="@(() => _showPicker = true)">
-                    Pick address
-                </button>
-            </div>
-
-            <DriverTagPicker @bind-Visible="_showPicker"
-                             Title="OPC UA address"
-                             CurrentAddress="@_pickedAddress"
-                             OnPickAddress="@OnAddressPicked">
-                <OpcUaClientAddressPickerBody CurrentAddress="@_pickedAddress"
-                                              CurrentAddressChanged="@((s) => _pickedAddress = s)"
-                                              GetConfigJson="@SerializeCurrentConfig" />
-            </DriverTagPicker>
-
-            @* Endpoint *@
-            <section class="panel rise mt-3" style="animation-delay:.06s">
-                <div class="panel-head">Endpoint</div>
-                <div style="padding:1rem">
-                    <div class="row g-3">
-                        <div class="col-md-8">
-                            <label class="form-label">Endpoint URL</label>
-                            <InputText @bind-Value="_form.OpcUa.EndpointUrl" class="form-control form-control-sm mono"
-                                       placeholder="opc.tcp://plc.internal:4840" />
-                            <div class="form-text">Single-endpoint shortcut. When EndpointUrls list is non-empty, this field is ignored.</div>
-                        </div>
-                        <div class="col-md-4">
-                            <label class="form-label">Browse root NodeId (blank = ObjectsFolder)</label>
-                            <InputText @bind-Value="_form.OpcUa.BrowseRoot" class="form-control form-control-sm mono"
-                                       placeholder="i=85" />
-                            <div class="form-text">Restrict mirroring to a sub-tree.</div>
-                        </div>
-                        <div class="col-md-4">
-                            <label class="form-label">Application URI</label>
-                            <InputText @bind-Value="_form.OpcUa.ApplicationUri" class="form-control form-control-sm mono" />
-                        </div>
-                        <div class="col-md-4">
-                            <label class="form-label">Session name</label>
-                            <InputText @bind-Value="_form.OpcUa.SessionName" class="form-control form-control-sm" />
-                        </div>
-                        <div class="col-md-4">
-                            <div class="form-check form-switch mt-4">
-                                <InputCheckbox @bind-Value="_form.OpcUa.AutoAcceptCertificates" class="form-check-input" id="autoAcceptCerts" />
-                                <label class="form-check-label" for="autoAcceptCerts">Auto-accept certificates <span class="badge bg-warning text-dark">Dev only</span></label>
-                            </div>
-                        </div>
-                    </div>
-                    <div class="row g-3 mt-1">
-                        <div class="col-md-3">
-                            <label class="form-label">Per-endpoint connect timeout (s)</label>
-                            <InputNumber @bind-Value="_form.OpcUa.PerEndpointConnectTimeoutSeconds" class="form-control form-control-sm" />
-                            <div class="form-text">Default 3 s — failover sweep budget.</div>
-                        </div>
-                        <div class="col-md-3">
-                            <label class="form-label">Operation timeout (s)</label>
-                            <InputNumber @bind-Value="_form.OpcUa.TimeoutSeconds" class="form-control form-control-sm" />
-                            <div class="form-text">Default 10 s — steady-state reads/writes.</div>
-                        </div>
-                        <div class="col-md-3">
-                            <label class="form-label">Session timeout (s)</label>
-                            <InputNumber @bind-Value="_form.OpcUa.SessionTimeoutSeconds" class="form-control form-control-sm" />
-                            <div class="form-text">Default 120 s.</div>
-                        </div>
-                        <div class="col-md-3">
-                            <label class="form-label">Keep-alive interval (s)</label>
-                            <InputNumber @bind-Value="_form.OpcUa.KeepAliveIntervalSeconds" class="form-control form-control-sm" />
-                            <div class="form-text">Default 5 s.</div>
-                        </div>
-                        <div class="col-md-3">
-                            <label class="form-label">Reconnect period (s)</label>
-                            <InputNumber @bind-Value="_form.OpcUa.ReconnectPeriodSeconds" class="form-control form-control-sm" />
-                            <div class="form-text">Initial delay after session drop. Default 5 s.</div>
-                        </div>
-                        <div class="col-md-3">
-                            <label class="form-label">Max discovered nodes</label>
-                            <InputNumber @bind-Value="_form.OpcUa.MaxDiscoveredNodes" class="form-control form-control-sm" />
-                            <div class="form-text">Default 10000.</div>
-                        </div>
-                        <div class="col-md-3">
-                            <label class="form-label">Max browse depth</label>
-                            <InputNumber @bind-Value="_form.OpcUa.MaxBrowseDepth" class="form-control form-control-sm" />
-                            <div class="form-text">Default 10.</div>
-                        </div>
-                    </div>
-                    <div class="row g-3 mt-1">
-                        <div class="col-12">
-                            <CollectionEditor TRow="EndpointUrlRow" Items="_endpoints"
-                                              Title="Endpoint URLs" ItemNoun="endpoint" AnimationDelay=".07s"
-                                              NewRow="@(() => new EndpointUrlRow())" Clone="@(r => r.Clone())"
-                                              Validate="EndpointUrlRow.ValidateRow">
-                                <HeaderTemplate>
-                                    <tr><th>Endpoint URL (failover list — first reachable wins)</th><th></th></tr>
-                                </HeaderTemplate>
-                                <RowTemplate Context="e">
-                                    <td class="mono">@e.Url</td>
-                                </RowTemplate>
-                                <EditTemplate Context="e">
-                                    <label class="form-label">Endpoint URL</label>
-                                    <input class="form-control form-control-sm mono" @bind="e.Url"
-                                           placeholder="opc.tcp://plc.internal:4840" />
-                                    <div class="form-text">When this list is non-empty, the single Endpoint URL above is ignored.</div>
-                                </EditTemplate>
-                            </CollectionEditor>
-                        </div>
-                    </div>
-                </div>
-            </section>
-
-            @* Security *@
-            <section class="panel rise mt-3" style="animation-delay:.08s">
-                <div class="panel-head">Security</div>
-                <div style="padding:1rem">
-                    <div class="row g-3">
-                        <div class="col-md-4">
-                            <label class="form-label">Security mode</label>
-                            <InputSelect @bind-Value="_form.OpcUa.SecurityMode" class="form-select form-select-sm">
-                                @foreach (var e in Enum.GetValues<OpcUaSecurityMode>())
-                                {
-                                    <option value="@e">@e</option>
-                                }
-                            </InputSelect>
-                        </div>
-                        <div class="col-md-4">
-                            <label class="form-label">Security policy</label>
-                            <InputSelect @bind-Value="_form.OpcUa.SecurityPolicy" class="form-select form-select-sm">
-                                @foreach (var e in Enum.GetValues<OpcUaSecurityPolicy>())
-                                {
-                                    <option value="@e">@e</option>
-                                }
-                            </InputSelect>
-                        </div>
-                    </div>
-                </div>
-            </section>
-
-            @* Authentication *@
-            <section class="panel rise mt-3" style="animation-delay:.10s">
-                <div class="panel-head">Authentication</div>
-                <div style="padding:1rem">
-                    <div class="row g-3">
-                        <div class="col-md-4">
-                            <label class="form-label">Auth type</label>
-                            <InputSelect @bind-Value="_form.OpcUa.AuthType" class="form-select form-select-sm">
-                                @foreach (var e in Enum.GetValues<OpcUaAuthType>())
-                                {
-                                    <option value="@e">@e</option>
-                                }
-                            </InputSelect>
-                        </div>
-                        @if (_form.OpcUa.AuthType == OpcUaAuthType.Username)
-                        {
-                            <div class="col-md-4">
-                                <label class="form-label">Username</label>
-                                <InputText @bind-Value="_form.OpcUa.Username" class="form-control form-control-sm" />
-                            </div>
-                            <div class="col-md-4">
-                                <label class="form-label">Password</label>
-                                <InputText @bind-Value="_form.OpcUa.Password" type="password" class="form-control form-control-sm" autocomplete="new-password" />
-                            </div>
-                        }
-                        @if (_form.OpcUa.AuthType == OpcUaAuthType.Certificate)
-                        {
-                            <div class="col-md-6">
-                                <label class="form-label">User certificate path (PFX/PEM)</label>
-                                <InputText @bind-Value="_form.OpcUa.UserCertificatePath" class="form-control form-control-sm mono"
-                                           placeholder="C:\certs\user.pfx" />
-                            </div>
-                            <div class="col-md-4">
-                                <label class="form-label">Certificate password (if PFX-locked)</label>
-                                <InputText @bind-Value="_form.OpcUa.UserCertificatePassword" type="password" class="form-control form-control-sm" autocomplete="new-password" />
-                            </div>
-                        }
-                    </div>
-                </div>
-            </section>
-
-            @* Namespace mapping *@
-            <section class="panel rise mt-3" style="animation-delay:.12s">
-                <div class="panel-head">Namespace mapping</div>
-                <div style="padding:1rem">
-                    <div class="row g-3">
-                        <div class="col-md-4">
-                            <label class="form-label">Target namespace kind</label>
-                            <InputSelect @bind-Value="_form.OpcUa.TargetNamespaceKind" class="form-select form-select-sm">
-                                @foreach (var e in Enum.GetValues<OpcUaTargetNamespaceKind>())
-                                {
-                                    <option value="@e">@e</option>
-                                }
-                            </InputSelect>
-                            <div class="form-text">Equipment = raw data re-mapped to UNS. SystemPlatform = processed data; hierarchy preserved as-is.</div>
-                        </div>
-                        <div class="col-12">
-                            <label class="form-label">UNS mapping table (read-only — edit via raw JSON import)</label>
-                            <pre class="form-control form-control-sm mono" style="min-height:3rem;overflow:auto;white-space:pre-wrap;">@_unsMappingTableJson</pre>
-                            <div class="form-text">Keys = remote browse-path prefixes; values = UNS Area/Line/Name paths. Required when TargetNamespaceKind = Equipment.</div>
-                        </div>
-                    </div>
-                </div>
-            </section>
-
-            @* Diagnostics *@
-            <section class="panel rise mt-3" style="animation-delay:.14s">
-                <div class="panel-head">Diagnostics</div>
-                <div style="padding:1rem">
-                    <div class="row g-3">
-                        <div class="col-md-3">
-                            <label class="form-label">Admin UI probe timeout (seconds)</label>
-                            <InputNumber @bind-Value="_form.OpcUa.ProbeTimeoutSeconds" class="form-control form-control-sm" />
-                            <div class="form-text">Max 60. Used by Test Connect. Default 15.</div>
-                        </div>
-                    </div>
-                </div>
-            </section>
-
-            <DriverResilienceSection @bind-ResilienceConfig="_form.ResilienceConfig" />
-        </DriverFormShell>
-    </EditForm>
-}
-
-@code {
-    [Parameter] public string ClusterId { get; set; } = "";
-    [Parameter] public string? DriverInstanceId { get; set; }
-
-    private const string DriverTypeKey = "OpcUaClient";
-
-    private bool IsNew => string.IsNullOrEmpty(DriverInstanceId);
-
-    private static readonly System.Text.Json.JsonSerializerOptions _jsonOpts = new()
-    {
-        PropertyNamingPolicy = System.Text.Json.JsonNamingPolicy.CamelCase,
-        UnmappedMemberHandling = System.Text.Json.Serialization.JsonUnmappedMemberHandling.Skip,
-        WriteIndented = false,
-        Converters = { new System.Text.Json.Serialization.JsonStringEnumConverter() },
-    };
-
-    private FormModel _form = new();
-    private DriverIdentitySection.DriverIdentityModel _identityModel = new() { DriverType = DriverTypeKey };
-    private DriverInstance? _existing;
-    private bool _loaded;
-    private bool _busy;
-    private string? _error;
-
-    // Address picker state
-    private bool _showPicker;
-    private string _pickedAddress = "";
-
-    private void OnAddressPicked(string address) => _pickedAddress = address;
-
-    // Held separately because EndpointUrls is a collection — edited via the CollectionEditor modal.
-    private List<EndpointUrlRow> _endpoints = [];
-
-    // Read-only JSON snippet for the UnsMappingTable, which has no list editor yet.
-    private string _unsMappingTableJson = "{}";
-
-    protected override async Task OnInitializedAsync()
-    {
-        await using var db = await DbFactory.CreateDbContextAsync();
-
-        if (IsNew)
-        {
-            _identityModel = new()
-            {
-                DriverInstanceId = "",
-                Name = "",
-                DriverType = DriverTypeKey,
-                Enabled = true,
-            };
-            _form = new FormModel();
-        }
-        else
-        {
-            _existing = await db.DriverInstances.AsNoTracking()
-                .FirstOrDefaultAsync(d => d.ClusterId == ClusterId && d.DriverInstanceId == DriverInstanceId);
-            if (_existing is not null)
-            {
-                _identityModel = new()
-                {
-                    DriverInstanceId = _existing.DriverInstanceId,
-                    Name = _existing.Name,
-                    DriverType = _existing.DriverType,
-                    Enabled = _existing.Enabled,
-                };
-                var opts = TryDeserialize(_existing.DriverConfig) ?? new OpcUaClientDriverOptions();
-                _form = new FormModel();
-                _form.OpcUa = OpcUaClientFormModel.FromRecord(opts);
-                _endpoints = opts.EndpointUrls.Select(EndpointUrlRow.FromUrl).ToList();
-                _unsMappingTableJson = System.Text.Json.JsonSerializer.Serialize(opts.UnsMappingTable, _jsonOpts);
-                _form.ResilienceConfig = _existing.ResilienceConfig;
-                _form.RowVersion = _existing.RowVersion;
-            }
-        }
-        _loaded = true;
-    }
-
-    private async Task SubmitAsync()
-    {
-        _busy = true; _error = null;
-        try
-        {
-            var opts = _form.OpcUa.ToRecord(_endpoints.Select(r => r.ToUrl()).ToList());
-            var configJson = System.Text.Json.JsonSerializer.Serialize(opts, _jsonOpts);
-            await using var db = await DbFactory.CreateDbContextAsync();
-            if (IsNew)
-            {
-                if (await db.DriverInstances.AnyAsync(d => d.DriverInstanceId == _identityModel.DriverInstanceId))
-                {
-                    _error = $"Driver instance '{_identityModel.DriverInstanceId}' already exists."; return;
-                }
-                db.DriverInstances.Add(new DriverInstance
-                {
-                    DriverInstanceId = _identityModel.DriverInstanceId,
-                    ClusterId = ClusterId,
-                    Name = _identityModel.Name,
-                    DriverType = DriverTypeKey,
-                    Enabled = _identityModel.Enabled,
-                    DriverConfig = configJson,
-                    ResilienceConfig = string.IsNullOrWhiteSpace(_form.ResilienceConfig) ? null : _form.ResilienceConfig,
-                });
-            }
-            else
-            {
-                var entity = await db.DriverInstances.FirstOrDefaultAsync(
-                    d => d.ClusterId == ClusterId && d.DriverInstanceId == DriverInstanceId);
-                if (entity is null) { _error = "Row no longer exists."; return; }
-                db.Entry(entity).Property(e => e.RowVersion).OriginalValue = _form.RowVersion;
-                entity.Name = _identityModel.Name;
-                entity.Enabled = _identityModel.Enabled;
-                entity.DriverConfig = configJson;
-                entity.ResilienceConfig = string.IsNullOrWhiteSpace(_form.ResilienceConfig) ? null : _form.ResilienceConfig;
-            }
-            await db.SaveChangesAsync();
-            Nav.NavigateTo($"/clusters/{ClusterId}/drivers");
-        }
-        catch (DbUpdateConcurrencyException)
-        {
-            _error = "Another user changed this driver instance while you were editing. Reload to see the latest values, then re-apply your changes.";
-        }
-        catch (Exception ex) { _error = ex.Message; }
-        finally { _busy = false; }
-    }
-
-    private async Task DeleteAsync()
-    {
-        if (IsNew) return;
-        _busy = true; _error = null;
-        try
-        {
-            await using var db = await DbFactory.CreateDbContextAsync();
-            var entity = await db.DriverInstances.FirstOrDefaultAsync(
-                d => d.ClusterId == ClusterId && d.DriverInstanceId == DriverInstanceId);
-            if (entity is null) { Nav.NavigateTo($"/clusters/{ClusterId}/drivers"); return; }
-            db.Entry(entity).Property(e => e.RowVersion).OriginalValue = _form.RowVersion;
-            db.DriverInstances.Remove(entity);
-            await db.SaveChangesAsync();
-            Nav.NavigateTo($"/clusters/{ClusterId}/drivers");
-        }
-        catch (DbUpdateConcurrencyException)
-        {
-            _error = "Another user changed this driver instance while you were viewing it. Reload before deleting.";
-        }
-        catch (Exception ex)
-        {
-            _error = $"Delete failed: {ex.Message}. (Likely because equipment/tags still reference this driver — remove them first.)";
-        }
-        finally { _busy = false; }
-    }
-
-    private string SerializeCurrentConfig()
-        => System.Text.Json.JsonSerializer.Serialize(
-            _form.OpcUa.ToRecord(_endpoints.Select(r => r.ToUrl()).ToList()), _jsonOpts);
-
-    private static OpcUaClientDriverOptions? TryDeserialize(string json)
-    {
-        try { return System.Text.Json.JsonSerializer.Deserialize<OpcUaClientDriverOptions>(json, _jsonOpts); }
-        catch { return null; }
-    }
-
-    public sealed class FormModel
-    {
-        public OpcUaClientFormModel OpcUa { get; set; } = new();
-        public string? ResilienceConfig { get; set; }
-        public byte[] RowVersion { get; set; } = [];
-    }
-
-    /// <summary>
-    ///     Mutable VM for a single endpoint URL row. EndpointUrls is a plain
-    ///     <c>List&lt;string&gt;</c> (a failover list) so the row is a thin wrapper the
-    ///     <see cref="CollectionEditor{TRow}"/> modal can bind to.
-    /// </summary>
-    public sealed class EndpointUrlRow
-    {
-        public string Url { get; set; } = "";
-        public EndpointUrlRow Clone() => (EndpointUrlRow)MemberwiseClone();
-        public static EndpointUrlRow FromUrl(string u) => new() { Url = u };
-        public string ToUrl() => Url.Trim();
-
-        public static string? ValidateRow(EndpointUrlRow row, IReadOnlyList<EndpointUrlRow> all, int? editIndex)
-        {
-            if (string.IsNullOrWhiteSpace(row.Url)) return "URL is required.";
-            if (!row.Url.Trim().StartsWith("opc.tcp://", StringComparison.OrdinalIgnoreCase))
-                return "Endpoint URL must start with opc.tcp://";
-            for (var i = 0; i < all.Count; i++)
-                if (i != editIndex && string.Equals(all[i].Url.Trim(), row.Url.Trim(), StringComparison.OrdinalIgnoreCase))
-                    return $"Duplicate endpoint '{row.Url}'.";
-            return null;
-        }
-    }
-
-    /// <summary>
-    ///     Mutable mirror of <see cref="OpcUaClientDriverOptions"/> with int wrappers for
-    ///     TimeSpan fields so Blazor InputNumber can bind them.
-    ///     EndpointUrls is edited via the CollectionEditor (held on the page as a row list and
-    ///     threaded into <see cref="ToRecord"/>); UnsMappingTable is shown as read-only JSON and
-    ///     survives round-trip via the original deserialized record, re-serialized unchanged.
-    /// </summary>
-    public sealed class OpcUaClientFormModel
-    {
-        // Connection
-        public string EndpointUrl { get; set; } = "opc.tcp://localhost:4840";
-        public string? BrowseRoot { get; set; }
-        public string ApplicationUri { get; set; } = "urn:localhost:OtOpcUa:GatewayClient";
-        public string SessionName { get; set; } = "OtOpcUa-Gateway";
-        public bool AutoAcceptCertificates { get; set; } = false;
-        public int PerEndpointConnectTimeoutSeconds { get; set; } = 3;
-        public int TimeoutSeconds { get; set; } = 10;
-        public int SessionTimeoutSeconds { get; set; } = 120;
-        public int KeepAliveIntervalSeconds { get; set; } = 5;
-        public int ReconnectPeriodSeconds { get; set; } = 5;
-        public int MaxDiscoveredNodes { get; set; } = 10_000;
-        public int MaxBrowseDepth { get; set; } = 10;
-
-        // Security
-        public OpcUaSecurityMode SecurityMode { get; set; } = OpcUaSecurityMode.None;
-        public OpcUaSecurityPolicy SecurityPolicy { get; set; } = OpcUaSecurityPolicy.None;
-
-        // Authentication
-        public OpcUaAuthType AuthType { get; set; } = OpcUaAuthType.Anonymous;
-        public string? Username { get; set; }
-        public string? Password { get; set; }
-        public string? UserCertificatePath { get; set; }
-        public string? UserCertificatePassword { get; set; }
-
-        // Namespace mapping
-        public OpcUaTargetNamespaceKind TargetNamespaceKind { get; set; } = OpcUaTargetNamespaceKind.Equipment;
-
-        // Diagnostics
-        public int ProbeTimeoutSeconds { get; set; } = 15;
-
-        // Preserved read-only collection (round-tripped unchanged from original record)
-        internal IReadOnlyDictionary<string, string> _unsMappingTable = new System.Collections.Generic.Dictionary<string, string>();
-
-        public static OpcUaClientFormModel FromRecord(OpcUaClientDriverOptions r) => new()
-        {
-            EndpointUrl = r.EndpointUrl,
-            BrowseRoot = r.BrowseRoot,
-            ApplicationUri = r.ApplicationUri,
-            SessionName = r.SessionName,
-            AutoAcceptCertificates = r.AutoAcceptCertificates,
-            PerEndpointConnectTimeoutSeconds = (int)r.PerEndpointConnectTimeout.TotalSeconds,
-            TimeoutSeconds = (int)r.Timeout.TotalSeconds,
-            SessionTimeoutSeconds = (int)r.SessionTimeout.TotalSeconds,
-            KeepAliveIntervalSeconds = (int)r.KeepAliveInterval.TotalSeconds,
-            ReconnectPeriodSeconds = (int)r.ReconnectPeriod.TotalSeconds,
-            MaxDiscoveredNodes = r.MaxDiscoveredNodes,
-            MaxBrowseDepth = r.MaxBrowseDepth,
-            SecurityMode = r.SecurityMode,
-            SecurityPolicy = r.SecurityPolicy,
-            AuthType = r.AuthType,
-            Username = r.Username,
-            Password = r.Password,
-            UserCertificatePath = r.UserCertificatePath,
-            UserCertificatePassword = r.UserCertificatePassword,
-            TargetNamespaceKind = r.TargetNamespaceKind,
-            ProbeTimeoutSeconds = r.ProbeTimeoutSeconds,
-            _unsMappingTable = r.UnsMappingTable,
-        };
-
-        public OpcUaClientDriverOptions ToRecord(IReadOnlyList<string> endpointUrls) => new()
-        {
-            EndpointUrl = EndpointUrl,
-            EndpointUrls = endpointUrls,
-            BrowseRoot = string.IsNullOrWhiteSpace(BrowseRoot) ? null : BrowseRoot,
-            ApplicationUri = ApplicationUri,
-            SessionName = SessionName,
-            AutoAcceptCertificates = AutoAcceptCertificates,
-            PerEndpointConnectTimeout = TimeSpan.FromSeconds(PerEndpointConnectTimeoutSeconds),
-            Timeout = TimeSpan.FromSeconds(TimeoutSeconds),
-            SessionTimeout = TimeSpan.FromSeconds(SessionTimeoutSeconds),
-            KeepAliveInterval = TimeSpan.FromSeconds(KeepAliveIntervalSeconds),
-            ReconnectPeriod = TimeSpan.FromSeconds(ReconnectPeriodSeconds),
-            MaxDiscoveredNodes = MaxDiscoveredNodes,
-            MaxBrowseDepth = MaxBrowseDepth,
-            SecurityMode = SecurityMode,
-            SecurityPolicy = SecurityPolicy,
-            AuthType = AuthType,
-            Username = string.IsNullOrWhiteSpace(Username) ? null : Username,
-            Password = string.IsNullOrWhiteSpace(Password) ? null : Password,
-            UserCertificatePath = string.IsNullOrWhiteSpace(UserCertificatePath) ? null : UserCertificatePath,
-            UserCertificatePassword = string.IsNullOrWhiteSpace(UserCertificatePassword) ? null : UserCertificatePassword,
-            TargetNamespaceKind = TargetNamespaceKind,
-            UnsMappingTable = _unsMappingTable,
-            ProbeTimeoutSeconds = ProbeTimeoutSeconds,
-        };
-    }
-}
@@ -1,356 +0,0 @@
-@page "/clusters/{ClusterId}/drivers/new/s7"
-@attribute [Authorize(Policy = AdminUiPolicies.ConfigEditor)]
-@rendermode RenderMode.InteractiveServer
-@using Microsoft.AspNetCore.Components.Forms
-@using Microsoft.EntityFrameworkCore
-@using ZB.MOM.WW.OtOpcUa.AdminUI.Clients
-@using ZB.MOM.WW.OtOpcUa.AdminUI.Components.Shared.Drivers
-@using ZB.MOM.WW.OtOpcUa.AdminUI.Components.Shared.Drivers.Pickers
-@using ZB.MOM.WW.OtOpcUa.Configuration
-@using ZB.MOM.WW.OtOpcUa.Configuration.Entities
-@using ZB.MOM.WW.OtOpcUa.Driver.S7
-@inject IDbContextFactory<OtOpcUaConfigDbContext> DbFactory
-@inject NavigationManager Nav
-
-<div class="d-flex justify-content-between align-items-center mb-3">
-    <h4 class="mb-0">@(IsNew ? "New Siemens S7 driver" : "Edit Siemens S7 driver") &middot; <span class="mono">@ClusterId</span></h4>
-    <a href="/clusters/@ClusterId/drivers" class="btn btn-outline-secondary btn-sm">Cancel</a>
-</div>
-<ClusterNav ClusterId="@ClusterId" ActiveTab="drivers" />
-
-@if (!_loaded)
-{
-    <p>Loading…</p>
-}
-else if (!IsNew && _existing is null)
-{
-    <section class="panel notice rise" style="animation-delay:.02s">
-        Driver instance <span class="mono">@DriverInstanceId</span> was not found in cluster <span class="mono">@ClusterId</span>.
-    </section>
-}
-else
-{
-    <EditForm Model="_form" OnValidSubmit="SubmitAsync" FormName="s7DriverEdit">
-        <DataAnnotationsValidator />
-        <DriverFormShell IsNew="IsNew" Busy="_busy" Error="@_error"
-                         CancelHref="@($"/clusters/{ClusterId}/drivers")"
-                         OnDelete="@(IsNew ? null : (EventCallback?)EventCallback.Factory.Create(this, DeleteAsync))">
-
-            <DriverIdentitySection Model="_identityModel" IsNew="IsNew" ShowDriverType="false" />
-
-            @if (!IsNew && !string.IsNullOrEmpty(DriverInstanceId))
-            {
-                <DriverStatusPanel DriverInstanceId="@DriverInstanceId" Enabled="@_identityModel.Enabled" />
-            }
-
-            <div class="mt-2 mb-3">
-                <DriverTestConnectButton DriverType="@DriverTypeKey"
-                                         GetConfigJson="@SerializeCurrentConfig"
-                                         TimeoutSeconds="@_form.AdminProbeTimeoutSeconds" />
-                <button type="button" class="btn btn-sm btn-outline-secondary mt-2"
-                        @onclick="@(() => _showPicker = true)">
-                    Pick address
-                </button>
-            </div>
-
-            <DriverTagPicker @bind-Visible="_showPicker"
-                             Title="S7 address"
-                             CurrentAddress="@_pickedAddress"
-                             OnPickAddress="@OnAddressPicked">
-                <S7AddressPickerBody CurrentAddress="@_pickedAddress"
-                                     CurrentAddressChanged="@((s) => _pickedAddress = s)" />
-            </DriverTagPicker>
-
-            @* Connection *@
-            <section class="panel rise mt-3" style="animation-delay:.05s">
-                <div class="panel-head">Connection</div>
-                <div style="padding:1rem">
-                    <div class="row">
-                        <div class="col-md-6 mb-3">
-                            <label class="form-label" for="s7Host">Host</label>
-                            <InputText id="s7Host" @bind-Value="_form.Host"
-                                       class="form-control form-control-sm mono"
-                                       placeholder="192.168.0.1" />
-                            <div class="form-text">PLC IP address or hostname.</div>
-                        </div>
-                        <div class="col-md-3 mb-3">
-                            <label class="form-label" for="s7Port">Port</label>
-                            <InputNumber id="s7Port" @bind-Value="_form.Port"
-                                         class="form-control form-control-sm" />
-                            <div class="form-text">ISO-on-TCP; usually 102.</div>
-                        </div>
-                        <div class="col-md-3 mb-3">
-                            <label class="form-label" for="s7TimeoutSec">Timeout (seconds)</label>
-                            <InputNumber id="s7TimeoutSec" @bind-Value="_form.TimeoutSeconds"
-                                         class="form-control form-control-sm" />
-                        </div>
-                    </div>
-                    <div class="row">
-                        <div class="col-md-4 mb-3">
-                            <label class="form-label" for="s7CpuType">CPU type</label>
-                            <InputSelect id="s7CpuType" @bind-Value="_form.CpuType"
-                                         class="form-select form-select-sm">
-                                @foreach (var v in Enum.GetValues<S7CpuType>())
-                                {
-                                    <option value="@v">@v</option>
-                                }
-                            </InputSelect>
-                            <div class="form-text">Controls ISO-TSAP slot byte during handshake.</div>
-                        </div>
-                        <div class="col-md-2 mb-3">
-                            <label class="form-label" for="s7Rack">Rack</label>
-                            <InputNumber id="s7Rack" @bind-Value="_form.Rack"
-                                         class="form-control form-control-sm" />
-                            <div class="form-text">Almost always 0.</div>
-                        </div>
-                        <div class="col-md-2 mb-3">
-                            <label class="form-label" for="s7Slot">Slot</label>
-                            <InputNumber id="s7Slot" @bind-Value="_form.Slot"
-                                         class="form-control form-control-sm" />
-                            <div class="form-text">S7-300/400 = 2; S7-1200/1500 = 0.</div>
-                        </div>
-                    </div>
-                </div>
-            </section>
-
-            @* Probe *@
-            <section class="panel rise mt-3" style="animation-delay:.08s">
-                <div class="panel-head">Connectivity probe</div>
-                <div style="padding:1rem">
-                    <div class="row">
-                        <div class="col-md-3 mb-3">
-                            <div class="form-check form-switch mt-2">
-                                <InputCheckbox id="s7ProbeEnabled" @bind-Value="_form.ProbeEnabled"
-                                               class="form-check-input" />
-                                <label class="form-check-label" for="s7ProbeEnabled">Probe enabled</label>
-                            </div>
-                        </div>
-                        <div class="col-md-3 mb-3">
-                            <label class="form-label" for="s7ProbeIntervalSec">Probe interval (s)</label>
-                            <InputNumber id="s7ProbeIntervalSec" @bind-Value="_form.ProbeIntervalSeconds"
-                                         class="form-control form-control-sm" />
-                        </div>
-                        <div class="col-md-3 mb-3">
-                            <label class="form-label" for="s7ProbeTimeoutSec">Probe timeout (s)</label>
-                            <InputNumber id="s7ProbeTimeoutSec" @bind-Value="_form.ProbeTimeoutSeconds"
-                                         class="form-control form-control-sm" />
-                        </div>
-                        <div class="col-md-3 mb-3">
-                            <label class="form-label" for="s7AdminProbeTimeout">Admin probe timeout (s)</label>
-                            <InputNumber id="s7AdminProbeTimeout" @bind-Value="_form.AdminProbeTimeoutSeconds"
-                                         class="form-control form-control-sm" />
-                            <div class="form-text">Test Connect timeout (1–60 s).</div>
-                        </div>
-                    </div>
-                </div>
-            </section>
-
-            @* Tags *@
-            <section class="panel notice rise mt-3" style="animation-delay:.18s">
-                <div class="panel-head">Tags</div>
-                <div style="padding:1rem" class="text-muted">
-                    Tag authoring moves to the Raw tree (<strong>/raw</strong>) in v3 Batch 2.
-                    Pre-declared driver tags have been retired.
-                </div>
-            </section>
-
-            <DriverResilienceSection @bind-ResilienceConfig="_form.ResilienceConfig" />
-        </DriverFormShell>
-    </EditForm>
-}
-
-@code {
-    [Parameter] public string ClusterId { get; set; } = "";
-    [Parameter] public string? DriverInstanceId { get; set; }
-
-    private const string DriverTypeKey = "S7";
-
-    private bool IsNew => string.IsNullOrEmpty(DriverInstanceId);
-
-    private static readonly System.Text.Json.JsonSerializerOptions _jsonOpts = new()
-    {
-        PropertyNamingPolicy = System.Text.Json.JsonNamingPolicy.CamelCase,
-        UnmappedMemberHandling = System.Text.Json.Serialization.JsonUnmappedMemberHandling.Skip,
-        WriteIndented = false,
-        Converters = { new System.Text.Json.Serialization.JsonStringEnumConverter() },
-    };
-
-    private FormModel _form = new();
-    private DriverIdentitySection.DriverIdentityModel _identityModel = new() { DriverType = DriverTypeKey };
-    private DriverInstance? _existing;
-    private bool _loaded, _busy;
-    private string? _error;
-
-    // Address picker state
-    private bool _showPicker;
-    private string _pickedAddress = "";
-
-    private void OnAddressPicked(string address) => _pickedAddress = address;
-
-    protected override async Task OnInitializedAsync()
-    {
-        await using var db = await DbFactory.CreateDbContextAsync();
-
-        if (IsNew)
-        {
-            _identityModel = new() { DriverType = DriverTypeKey, Enabled = true };
-            _form = FormModel.FromOptions(new S7DriverOptions());
-        }
-        else
-        {
-            _existing = await db.DriverInstances.AsNoTracking()
-                .FirstOrDefaultAsync(d => d.ClusterId == ClusterId && d.DriverInstanceId == DriverInstanceId);
-            if (_existing is not null)
-            {
-                _identityModel = new()
-                {
-                    DriverInstanceId = _existing.DriverInstanceId,
-                    Name = _existing.Name,
-                    DriverType = _existing.DriverType,
-                    Enabled = _existing.Enabled,
-                };
-                var opts = TryDeserialize(_existing.DriverConfig) ?? new S7DriverOptions();
-                _form = FormModel.FromOptions(opts);
-                _form.ResilienceConfig = _existing.ResilienceConfig;
-                _form.RowVersion = _existing.RowVersion;
-            }
-        }
-        _loaded = true;
-    }
-
-    private async Task SubmitAsync()
-    {
-        _busy = true; _error = null;
-        try
-        {
-            var opts = _form.ToOptions();
-            var configJson = System.Text.Json.JsonSerializer.Serialize(opts, _jsonOpts);
-            await using var db = await DbFactory.CreateDbContextAsync();
-            if (IsNew)
-            {
-                if (await db.DriverInstances.AnyAsync(d => d.DriverInstanceId == _identityModel.DriverInstanceId))
-                {
-                    _error = $"Driver instance '{_identityModel.DriverInstanceId}' already exists."; return;
-                }
-                db.DriverInstances.Add(new DriverInstance
-                {
-                    DriverInstanceId = _identityModel.DriverInstanceId,
-                    ClusterId = ClusterId,
-                    Name = _identityModel.Name,
-                    DriverType = DriverTypeKey,
-                    Enabled = _identityModel.Enabled,
-                    DriverConfig = configJson,
-                    ResilienceConfig = string.IsNullOrWhiteSpace(_form.ResilienceConfig) ? null : _form.ResilienceConfig,
-                });
-            }
-            else
-            {
-                var entity = await db.DriverInstances.FirstOrDefaultAsync(
-                    d => d.ClusterId == ClusterId && d.DriverInstanceId == DriverInstanceId);
-                if (entity is null) { _error = "Row no longer exists."; return; }
-                db.Entry(entity).Property(e => e.RowVersion).OriginalValue = _form.RowVersion;
-                entity.Name = _identityModel.Name;
-                entity.Enabled = _identityModel.Enabled;
-                entity.DriverConfig = configJson;
-                entity.ResilienceConfig = string.IsNullOrWhiteSpace(_form.ResilienceConfig) ? null : _form.ResilienceConfig;
-            }
-            await db.SaveChangesAsync();
-            Nav.NavigateTo($"/clusters/{ClusterId}/drivers");
-        }
-        catch (DbUpdateConcurrencyException)
-        {
-            _error = "Another user changed this driver instance while you were editing. Reload to see the latest values, then re-apply your changes.";
-        }
-        catch (Exception ex) { _error = ex.Message; }
-        finally { _busy = false; }
-    }
-
-    private async Task DeleteAsync()
-    {
-        if (IsNew) return;
-        _busy = true; _error = null;
-        try
-        {
-            await using var db = await DbFactory.CreateDbContextAsync();
-            var entity = await db.DriverInstances.FirstOrDefaultAsync(
-                d => d.ClusterId == ClusterId && d.DriverInstanceId == DriverInstanceId);
-            if (entity is null) { Nav.NavigateTo($"/clusters/{ClusterId}/drivers"); return; }
-            db.Entry(entity).Property(e => e.RowVersion).OriginalValue = _form.RowVersion;
-            db.DriverInstances.Remove(entity);
-            await db.SaveChangesAsync();
-            Nav.NavigateTo($"/clusters/{ClusterId}/drivers");
-        }
-        catch (DbUpdateConcurrencyException)
-        {
-            _error = "Another user changed this driver instance while you were viewing it. Reload before deleting.";
-        }
-        catch (Exception ex)
-        {
-            _error = $"Delete failed: {ex.Message}. (Likely because equipment/tags still reference this driver — remove them first.)";
-        }
-        finally { _busy = false; }
-    }
-
-    private string SerializeCurrentConfig()
-        => System.Text.Json.JsonSerializer.Serialize(
-            _form.ToOptions(), _jsonOpts);
-
-    private static S7DriverOptions? TryDeserialize(string json)
-    {
-        try { return System.Text.Json.JsonSerializer.Deserialize<S7DriverOptions>(json, _jsonOpts); }
-        catch { return null; }
-    }
-
-    // Flat mutable model — all scalar properties settable for Blazor @bind-Value.
-    public sealed class FormModel
-    {
-        // Connection
-        public string Host { get; set; } = "127.0.0.1";
-        public int Port { get; set; } = 102;
-        public S7CpuType CpuType { get; set; } = S7CpuType.S71500;
-        public short Rack { get; set; } = 0;
-        public short Slot { get; set; } = 0;
-        public int TimeoutSeconds { get; set; } = 5;
-
-        // Probe
-        public bool ProbeEnabled { get; set; } = true;
-        public int ProbeIntervalSeconds { get; set; } = 5;
-        public int ProbeTimeoutSeconds { get; set; } = 2;
-        public int AdminProbeTimeoutSeconds { get; set; } = 5;
-
-        // Common
-        public string? ResilienceConfig { get; set; }
-        public byte[] RowVersion { get; set; } = [];
-
-        public static FormModel FromOptions(S7DriverOptions o) => new()
-        {
-            Host = o.Host,
-            Port = o.Port,
-            CpuType = o.CpuType,
-            Rack = o.Rack,
-            Slot = o.Slot,
-            TimeoutSeconds = (int)o.Timeout.TotalSeconds,
-            ProbeEnabled = o.Probe.Enabled,
-            ProbeIntervalSeconds = (int)o.Probe.Interval.TotalSeconds,
-            ProbeTimeoutSeconds = (int)o.Probe.Timeout.TotalSeconds,
-            AdminProbeTimeoutSeconds = o.ProbeTimeoutSeconds,
-        };
-
-        public S7DriverOptions ToOptions() => new()
-        {
-            Host = Host,
-            Port = Port,
-            CpuType = CpuType,
-            Rack = Rack,
-            Slot = Slot,
-            Timeout = TimeSpan.FromSeconds(TimeoutSeconds),
-            Probe = new S7ProbeOptions
-            {
-                Enabled = ProbeEnabled,
-                Interval = TimeSpan.FromSeconds(ProbeIntervalSeconds),
-                Timeout = TimeSpan.FromSeconds(ProbeTimeoutSeconds),
-            },
-            ProbeTimeoutSeconds = AdminProbeTimeoutSeconds,
-        };
-    }
-}
@@ -1,410 +0,0 @@
-@page "/clusters/{ClusterId}/drivers/new/twincat"
-@attribute [Authorize(Policy = AdminUiPolicies.ConfigEditor)]
-@rendermode RenderMode.InteractiveServer
-@using Microsoft.AspNetCore.Components.Forms
-@using Microsoft.EntityFrameworkCore
-@using ZB.MOM.WW.OtOpcUa.AdminUI.Clients
-@using ZB.MOM.WW.OtOpcUa.AdminUI.Components.Shared.Drivers
-@using ZB.MOM.WW.OtOpcUa.AdminUI.Components.Shared.Drivers.Pickers
-@using ZB.MOM.WW.OtOpcUa.Configuration
-@using ZB.MOM.WW.OtOpcUa.Configuration.Entities
-@using ZB.MOM.WW.OtOpcUa.Driver.TwinCAT
-@inject IDbContextFactory<OtOpcUaConfigDbContext> DbFactory
-@inject NavigationManager Nav
-
-<div class="d-flex justify-content-between align-items-center mb-3">
-    <h4 class="mb-0">@(IsNew ? "New Beckhoff TwinCAT driver" : "Edit Beckhoff TwinCAT driver") &middot; <span class="mono">@ClusterId</span></h4>
-    <a href="/clusters/@ClusterId/drivers" class="btn btn-outline-secondary btn-sm">Cancel</a>
-</div>
-<ClusterNav ClusterId="@ClusterId" ActiveTab="drivers" />
-
-@if (!_loaded)
-{
-    <p>Loading…</p>
-}
-else if (!IsNew && _existing is null)
-{
-    <section class="panel notice rise" style="animation-delay:.02s">
-        Driver instance <span class="mono">@DriverInstanceId</span> was not found in cluster <span class="mono">@ClusterId</span>.
-    </section>
-}
-else
-{
-    <EditForm Model="_form" OnValidSubmit="SubmitAsync" FormName="twincatDriverEdit">
-        <DataAnnotationsValidator />
-        <DriverFormShell IsNew="IsNew" Busy="_busy" Error="@_error"
-                         CancelHref="@($"/clusters/{ClusterId}/drivers")"
-                         OnDelete="@(IsNew ? null : (EventCallback?)EventCallback.Factory.Create(this, DeleteAsync))">
-
-            <DriverIdentitySection Model="_identityModel" IsNew="IsNew" ShowDriverType="false" />
-
-            @if (!IsNew && !string.IsNullOrEmpty(DriverInstanceId))
-            {
-                <DriverStatusPanel DriverInstanceId="@DriverInstanceId" Enabled="@_identityModel.Enabled" />
-            }
-
-            <div class="mt-2 mb-3">
-                <DriverTestConnectButton DriverType="@DriverTypeKey"
-                                         GetConfigJson="@SerializeCurrentConfig"
-                                         TimeoutSeconds="@_form.AdminProbeTimeoutSeconds" />
-                <button type="button" class="btn btn-sm btn-outline-secondary mt-2"
-                        @onclick="@(() => _showPicker = true)">
-                    Pick address
-                </button>
-            </div>
-
-            <DriverTagPicker @bind-Visible="_showPicker"
-                             Title="TwinCAT address"
-                             CurrentAddress="@_pickedAddress"
-                             OnPickAddress="@OnAddressPicked">
-                <TwinCATAddressPickerBody CurrentAddress="@_pickedAddress"
-                                          CurrentAddressChanged="@((s) => _pickedAddress = s)"
-                                          GetConfigJson="@SerializeCurrentConfig" />
-            </DriverTagPicker>
-
-            @* Options *@
-            <section class="panel rise mt-3" style="animation-delay:.05s">
-                <div class="panel-head">Options</div>
-                <div style="padding:1rem">
-                    <div class="row">
-                        <div class="col-md-3 mb-3">
-                            <label class="form-label" for="tcTimeoutSec">Timeout (seconds)</label>
-                            <InputNumber id="tcTimeoutSec" @bind-Value="_form.TimeoutSeconds"
-                                         class="form-control form-control-sm" />
-                            <div class="form-text">Default 2 s per operation.</div>
-                        </div>
-                        <div class="col-md-4 mb-3">
-                            <div class="form-check form-switch mt-4">
-                                <InputCheckbox id="tcNativeNotif" @bind-Value="_form.UseNativeNotifications"
-                                               class="form-check-input" />
-                                <label class="form-check-label" for="tcNativeNotif">Use native ADS notifications</label>
-                            </div>
-                            <div class="form-text">Recommended. Disable for AMS routers with notification limits.</div>
-                        </div>
-                        <div class="col-md-4 mb-3">
-                            <div class="form-check form-switch mt-4">
-                                <InputCheckbox id="tcControllerBrowse" @bind-Value="_form.EnableControllerBrowse"
-                                               class="form-check-input" />
-                                <label class="form-check-label" for="tcControllerBrowse">Enable controller browse</label>
-                            </div>
-                            <div class="form-text">Walks the symbol table via SymbolLoaderFactory at discovery. Default off.</div>
-                        </div>
-                    </div>
-                    <div class="row">
-                        <div class="col-md-4 mb-3">
-                            <label class="form-label" for="tcNotifDelay">Notification max delay (ms)</label>
-                            <InputNumber id="tcNotifDelay" @bind-Value="_form.NotificationMaxDelayMs"
-                                         class="form-control form-control-sm" />
-                            <div class="form-text">0 = push immediately. Increase to coalesce high-churn signals.</div>
-                        </div>
-                    </div>
-                </div>
-            </section>
-
-            @* Probe *@
-            <section class="panel rise mt-3" style="animation-delay:.08s">
-                <div class="panel-head">Connectivity probe</div>
-                <div style="padding:1rem">
-                    <div class="row">
-                        <div class="col-md-3 mb-3">
-                            <div class="form-check form-switch mt-2">
-                                <InputCheckbox id="tcProbeEnabled" @bind-Value="_form.ProbeEnabled"
-                                               class="form-check-input" />
-                                <label class="form-check-label" for="tcProbeEnabled">Probe enabled</label>
-                            </div>
-                        </div>
-                        <div class="col-md-3 mb-3">
-                            <label class="form-label" for="tcProbeInterval">Probe interval (s)</label>
-                            <InputNumber id="tcProbeInterval" @bind-Value="_form.ProbeIntervalSeconds"
-                                         class="form-control form-control-sm" />
-                        </div>
-                        <div class="col-md-3 mb-3">
-                            <label class="form-label" for="tcProbeTimeout">Probe timeout (s)</label>
-                            <InputNumber id="tcProbeTimeout" @bind-Value="_form.ProbeTimeoutSeconds"
-                                         class="form-control form-control-sm" />
-                        </div>
-                        <div class="col-md-3 mb-3">
-                            <label class="form-label" for="tcAdminProbe">Admin probe timeout (s)</label>
-                            <InputNumber id="tcAdminProbe" @bind-Value="_form.AdminProbeTimeoutSeconds"
-                                         class="form-control form-control-sm" />
-                            <div class="form-text">Test Connect timeout (1–60 s).</div>
-                        </div>
-                    </div>
-                </div>
-            </section>
-
-            @* Devices *@
-            <CollectionEditor TRow="TwinCATDeviceRow" Items="_devices" Title="Devices" ItemNoun="device"
-                              AnimationDelay=".11s"
-                              NewRow="@(() => new TwinCATDeviceRow())" Clone="@(r => r.Clone())"
-                              Validate="TwinCATDeviceRow.ValidateRow">
-                <HeaderTemplate>
-                    <tr><th>Host address</th><th>Device name</th><th></th></tr>
-                </HeaderTemplate>
-                <RowTemplate Context="d">
-                    <td class="mono">@d.HostAddress</td>
-                    <td>@(string.IsNullOrWhiteSpace(d.DeviceName) ? "—" : d.DeviceName)</td>
-                </RowTemplate>
-                <EditTemplate Context="d">
-                    <div class="row g-3">
-                        <div class="col-md-6"><label class="form-label">Host address (AMS Net Id:port)</label>
-                            <input class="form-control form-control-sm mono" @bind="d.HostAddress"
-                                   placeholder="192.168.0.1.1.1:851" /></div>
-                        <div class="col-md-6"><label class="form-label">Device name</label>
-                            <input class="form-control form-control-sm" @bind="d.DeviceName" /></div>
-                    </div>
-                </EditTemplate>
-            </CollectionEditor>
-
-            @* Tags *@
-            <section class="panel notice rise mt-3" style="animation-delay:.18s">
-                <div class="panel-head">Tags</div>
-                <div style="padding:1rem" class="text-muted">
-                    Tag authoring moves to the Raw tree (<strong>/raw</strong>) in v3 Batch 2.
-                    Pre-declared driver tags have been retired.
-                </div>
-            </section>
-
-            <DriverResilienceSection @bind-ResilienceConfig="_form.ResilienceConfig" />
-        </DriverFormShell>
-    </EditForm>
-}
-
-@code {
-    [Parameter] public string ClusterId { get; set; } = "";
-    [Parameter] public string? DriverInstanceId { get; set; }
-
-    private const string DriverTypeKey = "TwinCat";
-
-    private bool IsNew => string.IsNullOrEmpty(DriverInstanceId);
-
-    private static readonly System.Text.Json.JsonSerializerOptions _jsonOpts = new()
-    {
-        PropertyNamingPolicy = System.Text.Json.JsonNamingPolicy.CamelCase,
-        UnmappedMemberHandling = System.Text.Json.Serialization.JsonUnmappedMemberHandling.Skip,
-        WriteIndented = false,
-        Converters = { new System.Text.Json.Serialization.JsonStringEnumConverter() },
-    };
-
-    private FormModel _form = new();
-    private DriverIdentitySection.DriverIdentityModel _identityModel = new() { DriverType = DriverTypeKey };
-    private DriverInstance? _existing;
-    private bool _loaded, _busy;
-    private string? _error;
-
-    // Address picker state
-    private bool _showPicker;
-    private string _pickedAddress = "";
-
-    private void OnAddressPicked(string address) => _pickedAddress = address;
-
-    // Held separately because Devices is a collection — edited via the CollectionEditor modal.
-    private List<TwinCATDeviceRow> _devices = [];
-
-    protected override async Task OnInitializedAsync()
-    {
-        await using var db = await DbFactory.CreateDbContextAsync();
-
-        if (IsNew)
-        {
-            _identityModel = new() { DriverType = DriverTypeKey, Enabled = true };
-            _form = FormModel.FromOptions(new TwinCATDriverOptions());
-        }
-        else
-        {
-            _existing = await db.DriverInstances.AsNoTracking()
-                .FirstOrDefaultAsync(d => d.ClusterId == ClusterId && d.DriverInstanceId == DriverInstanceId);
-            if (_existing is not null)
-            {
-                _identityModel = new()
-                {
-                    DriverInstanceId = _existing.DriverInstanceId,
-                    Name = _existing.Name,
-                    DriverType = _existing.DriverType,
-                    Enabled = _existing.Enabled,
-                };
-                var opts = TryDeserialize(_existing.DriverConfig) ?? new TwinCATDriverOptions();
-                _form = FormModel.FromOptions(opts);
-                _form.ResilienceConfig = _existing.ResilienceConfig;
-                _form.RowVersion = _existing.RowVersion;
-                _devices = opts.Devices.Select(TwinCATDeviceRow.FromDefinition).ToList();
-            }
-        }
-        _loaded = true;
-    }
-
-    private async Task SubmitAsync()
-    {
-        _busy = true; _error = null;
-        try
-        {
-            var configJson = System.Text.Json.JsonSerializer.Serialize(
-                _form.ToOptions(
-                    _devices.Select(r => r.ToDefinition()).ToList()),
-                _jsonOpts);
-            await using var db = await DbFactory.CreateDbContextAsync();
-            if (IsNew)
-            {
-                if (await db.DriverInstances.AnyAsync(d => d.DriverInstanceId == _identityModel.DriverInstanceId))
-                {
-                    _error = $"Driver instance '{_identityModel.DriverInstanceId}' already exists."; return;
-                }
-                db.DriverInstances.Add(new DriverInstance
-                {
-                    DriverInstanceId = _identityModel.DriverInstanceId,
-                    ClusterId = ClusterId,
-                    Name = _identityModel.Name,
-                    DriverType = DriverTypeKey,
-                    Enabled = _identityModel.Enabled,
-                    DriverConfig = configJson,
-                    ResilienceConfig = string.IsNullOrWhiteSpace(_form.ResilienceConfig) ? null : _form.ResilienceConfig,
-                });
-            }
-            else
-            {
-                var entity = await db.DriverInstances.FirstOrDefaultAsync(
-                    d => d.ClusterId == ClusterId && d.DriverInstanceId == DriverInstanceId);
-                if (entity is null) { _error = "Row no longer exists."; return; }
-                db.Entry(entity).Property(e => e.RowVersion).OriginalValue = _form.RowVersion;
-                entity.Name = _identityModel.Name;
-                entity.Enabled = _identityModel.Enabled;
-                entity.DriverConfig = configJson;
-                entity.ResilienceConfig = string.IsNullOrWhiteSpace(_form.ResilienceConfig) ? null : _form.ResilienceConfig;
-            }
-            await db.SaveChangesAsync();
-            Nav.NavigateTo($"/clusters/{ClusterId}/drivers");
-        }
-        catch (DbUpdateConcurrencyException)
-        {
-            _error = "Another user changed this driver instance while you were editing. Reload to see the latest values, then re-apply your changes.";
-        }
-        catch (Exception ex) { _error = ex.Message; }
-        finally { _busy = false; }
-    }
-
-    private async Task DeleteAsync()
-    {
-        if (IsNew) return;
-        _busy = true; _error = null;
-        try
-        {
-            await using var db = await DbFactory.CreateDbContextAsync();
-            var entity = await db.DriverInstances.FirstOrDefaultAsync(
-                d => d.ClusterId == ClusterId && d.DriverInstanceId == DriverInstanceId);
-            if (entity is null) { Nav.NavigateTo($"/clusters/{ClusterId}/drivers"); return; }
-            db.Entry(entity).Property(e => e.RowVersion).OriginalValue = _form.RowVersion;
-            db.DriverInstances.Remove(entity);
-            await db.SaveChangesAsync();
-            Nav.NavigateTo($"/clusters/{ClusterId}/drivers");
-        }
-        catch (DbUpdateConcurrencyException)
-        {
-            _error = "Another user changed this driver instance while you were viewing it. Reload before deleting.";
-        }
-        catch (Exception ex)
-        {
-            _error = $"Delete failed: {ex.Message}. (Likely because equipment/tags still reference this driver — remove them first.)";
-        }
-        finally { _busy = false; }
-    }
-
-    private string SerializeCurrentConfig()
-        => System.Text.Json.JsonSerializer.Serialize(
-            _form.ToOptions(
-                _devices.Select(r => r.ToDefinition()).ToList()),
-            _jsonOpts);
-
-    private static TwinCATDriverOptions? TryDeserialize(string json)
-    {
-        try { return System.Text.Json.JsonSerializer.Deserialize<TwinCATDriverOptions>(json, _jsonOpts); }
-        catch { return null; }
-    }
-
-    // Mutable VM for the modal editor — TwinCATDeviceOptions is an immutable record.
-    public sealed class TwinCATDeviceRow
-    {
-        public string HostAddress { get; set; } = "";
-        public string? DeviceName { get; set; }
-
-        // Original record (null for newly-added rows). Preserves any fields the editor doesn't
-        // expose across a load→save.
-        private TwinCATDeviceOptions? _source;
-
-        public TwinCATDeviceRow Clone() => (TwinCATDeviceRow)MemberwiseClone(); // _source is an immutable record ref — safe to share
-
-        public static TwinCATDeviceRow FromDefinition(TwinCATDeviceOptions d) => new()
-        {
-            HostAddress = d.HostAddress, DeviceName = d.DeviceName,
-            _source = d,
-        };
-
-        public TwinCATDeviceOptions ToDefinition()
-        {
-            var baseDef = _source ?? new TwinCATDeviceOptions(HostAddress.Trim());
-            return baseDef with
-            {
-                HostAddress = HostAddress.Trim(),
-                DeviceName = string.IsNullOrWhiteSpace(DeviceName) ? null : DeviceName.Trim(),
-            };
-        }
-
-        public static string? ValidateRow(TwinCATDeviceRow row, IReadOnlyList<TwinCATDeviceRow> all, int? editIndex)
-        {
-            if (string.IsNullOrWhiteSpace(row.HostAddress)) return "Host address is required.";
-            for (var i = 0; i < all.Count; i++)
-                if (i != editIndex && string.Equals(all[i].HostAddress, row.HostAddress, StringComparison.OrdinalIgnoreCase))
-                    return $"Duplicate device host address '{row.HostAddress}'.";
-            return null;
-        }
-    }
-
-    // Flat mutable model — all scalar properties settable for Blazor @bind-Value.
-    // The Devices collection is kept on the component and passed in on ToOptions().
-    public sealed class FormModel
-    {
-        // Options
-        public int TimeoutSeconds { get; set; } = 2;
-        public bool UseNativeNotifications { get; set; } = true;
-        public bool EnableControllerBrowse { get; set; } = false;
-        public int NotificationMaxDelayMs { get; set; } = 0;
-
-        // Probe
-        public bool ProbeEnabled { get; set; } = true;
-        public int ProbeIntervalSeconds { get; set; } = 5;
-        public int ProbeTimeoutSeconds { get; set; } = 2;
-        public int AdminProbeTimeoutSeconds { get; set; } = 10;
-
-        // Common
-        public string? ResilienceConfig { get; set; }
-        public byte[] RowVersion { get; set; } = [];
-
-        public static FormModel FromOptions(TwinCATDriverOptions o) => new()
-        {
-            TimeoutSeconds = (int)o.Timeout.TotalSeconds,
-            UseNativeNotifications = o.UseNativeNotifications,
-            EnableControllerBrowse = o.EnableControllerBrowse,
-            NotificationMaxDelayMs = o.NotificationMaxDelayMs,
-            ProbeEnabled = o.Probe.Enabled,
-            ProbeIntervalSeconds = (int)o.Probe.Interval.TotalSeconds,
-            ProbeTimeoutSeconds = (int)o.Probe.Timeout.TotalSeconds,
-            AdminProbeTimeoutSeconds = o.ProbeTimeoutSeconds,
-        };
-
-        public TwinCATDriverOptions ToOptions(
-            IReadOnlyList<TwinCATDeviceOptions> devices) => new()
-        {
-            Timeout = TimeSpan.FromSeconds(TimeoutSeconds),
-            UseNativeNotifications = UseNativeNotifications,
-            EnableControllerBrowse = EnableControllerBrowse,
-            NotificationMaxDelayMs = NotificationMaxDelayMs,
-            Probe = new TwinCATProbeOptions
-            {
-                Enabled = ProbeEnabled,
-                Interval = TimeSpan.FromSeconds(ProbeIntervalSeconds),
-                Timeout = TimeSpan.FromSeconds(ProbeTimeoutSeconds),
-            },
-            ProbeTimeoutSeconds = AdminProbeTimeoutSeconds,
-            Devices = devices,
-        };
-    }
-}
@@ -0,0 +1,39 @@
+@page "/dev/context-menu-demo"
+@* Dev-only host page to live-verify the reusable ContextMenu component. *@
+@attribute [Authorize(Policy = AdminUiPolicies.AuthenticatedRead)]
+@rendermode InteractiveServer
+
+<PageTitle>ContextMenu demo</PageTitle>
+
+<h1>ContextMenu demo</h1>
+<p>Right-click the card below, or use the <strong>⋯</strong> button.</p>
+
+<div style="display:flex; align-items:center; gap:1rem; margin:1rem 0;">
+    <ContextMenu Items="_items" ShowEllipsis="false">
+        <div style="padding:2rem 3rem; border:1px dashed var(--bs-border-color); border-radius:.5rem; user-select:none;">
+            Right-click me
+        </div>
+    </ContextMenu>
+
+    <ContextMenu Items="_items" ShowEllipsis="true" />
+</div>
+
+<p>Last action: <strong>@_lastAction</strong></p>
+
+@code {
+    private string _lastAction = "(none)";
+
+    private IReadOnlyList<ContextMenuItem> _items => new List<ContextMenuItem>
+    {
+        new() { Label = "Edit", Icon = "✏️", OnClick = () => Set("Edit") },
+        new() { Label = "Duplicate", Icon = "📄", OnClick = () => Set("Duplicate") },
+        ContextMenuItem.Separator(),
+        new() { Label = "Delete", Icon = "🗑️", Disabled = true, OnClick = () => Set("Delete") },
+    };
+
+    private Task Set(string action)
+    {
+        _lastAction = action;
+        return Task.CompletedTask;
+    }
+}
@@ -0,0 +1,74 @@
+@page "/raw"
+@attribute [Authorize(Policy = AdminUiPolicies.ConfigEditor)]
+@rendermode RenderMode.InteractiveServer
+@using ZB.MOM.WW.OtOpcUa.AdminUI.Uns
+@using ZB.MOM.WW.OtOpcUa.AdminUI.Components.Shared.Raw
+@inject IRawTreeService Svc
+
+@* Peer of GlobalUns (/uns) for the v3 Raw project tree — the cluster-rooted
+   Enterprise → Cluster → Folder → Driver → Device → TagGroup → Tag hierarchy.
+   Loads the eager roots on init, then hands off to RawTree, which lazily expands
+   each container via IRawTreeService.LoadChildrenAsync and surfaces per-node
+   context menus (real create/configure/tag modals arrive in later Batch-2 waves). *@
+
+<PageTitle>Raw</PageTitle>
+
+<div class="d-flex justify-content-between align-items-center mb-3">
+    <h4 class="mb-0">Raw</h4>
+    <span class="text-muted small">Changes apply on the next deployment.</span>
+</div>
+
+<section class="panel rise" style="animation-delay:.02s">
+    <div class="panel-head d-flex justify-content-between align-items-center flex-wrap gap-2">
+        <span>Project tree</span>
+    </div>
+
+    @if (_loading)
+    {
+        <div style="padding:1rem" class="text-muted">
+            <span class="spinner-border spinner-border-sm me-1"></span>Loading…
+        </div>
+    }
+    else if (_loadError is not null)
+    {
+        <div style="padding:1rem" class="text-danger">@_loadError</div>
+    }
+    else if (_roots.Count == 0)
+    {
+        <div style="padding:1rem" class="text-muted">No clusters yet.</div>
+    }
+    else
+    {
+        <div style="padding:.5rem 1rem">
+            <RawTree Roots="_roots" />
+        </div>
+    }
+</section>
+
+@code {
+    private IReadOnlyList<RawNode> _roots = Array.Empty<RawNode>();
+    private bool _loading = true;
+    private string? _loadError;
+
+    protected override async Task OnInitializedAsync()
+    {
+        try
+        {
+            _roots = await Svc.LoadRootsAsync();
+            // Auto-expand the Enterprise roots so the Cluster level (which owns the lazy plumbing) is
+            // visible on load, mirroring GlobalUns.ExpandStructural. Enterprise children (clusters) are
+            // eagerly materialised by LoadRootsAsync, so this needs no lazy fetch; clusters stay
+            // collapsed and load their folders/drivers on first expand.
+            foreach (var enterprise in _roots)
+                enterprise.Expanded = true;
+        }
+        catch (Exception ex)
+        {
+            _loadError = $"Failed to load the Raw tree: {ex.Message}";
+        }
+        finally
+        {
+            _loading = false;
+        }
+    }
+}
@@ -0,0 +1,20 @@
+@page "/admin/secrets"
+@attribute [Authorize(Policy = ZB.MOM.WW.Secrets.Ui.SecretsAuthorization.ManagePolicy)]
+@rendermode RenderMode.InteractiveServer
+@using ZB.MOM.WW.Secrets.Ui
+
+@* Host-side wrapper for the ZB.MOM.WW.Secrets.Ui secrets page (lmxopcua#483).
+
+   This host's <Routes/> is deliberately static (cookie SignInAsync needs SSR), so every
+   interactive page opts in per-page with @rendermode — a directive the RCL's own routable
+   SecretsPage cannot carry, because the other three family hosts render it under a globally
+   interactive router where a nested render mode throws. Routing straight to the RCL page
+   therefore produced a statically-rendered, dead page here: no circuit, @onclick inert.
+
+   So this wrapper owns the /admin/secrets route in THIS host (the RCL assembly is no longer
+   passed to either AdditionalAssemblies registration — doing both would make the route
+   ambiguous), carries the standard per-page render mode, re-states the RCL page's own
+   authorization policy (the router only enforces [Authorize] on the routed page itself,
+   which is now this one), and renders the RCL page as an ordinary child component. *@
+
+<SecretsPage />
@@ -78,17 +78,9 @@ else
                    </InputSelect>
                    <ValidationMessage For="@(() => _form.UnsLineId)" />
                </div>
-                <div class="col-md-6 mb-3">
-                    <label class="form-label" for="eq-driver">Driver instance</label>
-                    <InputSelect id="eq-driver" @bind-Value="_form.DriverInstanceId" class="form-select form-select-sm">
-                        <option value="">(none / driver-less)</option>
-                        @foreach (var (id, display) in _driverOptions)
-                        {
-                            <option value="@id">@display</option>
-                        }
-                    </InputSelect>
-                </div>
            </div>
+            @* v3: equipment no longer binds a driver — device I/O is authored in the /raw tree and surfaced
+               here by reference on the Tags tab. The old "Driver instance" select was removed. *@
            <div class="row">
                <div class="col-md-6 mb-3">
                    <label class="form-label" for="eq-ztag">ZTag (ERP)</label>
@@ -138,38 +130,48 @@ else
    }
    else if (_activeTab == "tags")
    {
+        @* v3 Batch 3: equipment is reference-only — the Tags tab lists UnsTagReference rows pointing at
+           raw tags. Datatype/access are inherited (read-only) from the backing raw tag; the display-name
+           override is the only per-reference editable field. *@
        <div class="d-flex justify-content-end align-items-center gap-2 mb-2">
-            <button type="button" class="btn btn-outline-primary btn-sm" @onclick="OpenAddTag">Add tag</button>
+            <button type="button" class="btn btn-outline-primary btn-sm" @onclick="OpenAddReference">+ Add reference</button>
        </div>
-        @if (!string.IsNullOrWhiteSpace(_tagError))
+        @if (!string.IsNullOrWhiteSpace(_refError))
        {
-            <div class="text-danger small mb-2">@_tagError</div>
+            <div class="text-danger small mb-2">@_refError</div>
        }
-        @if (_tags is null)
+        @if (_refs is null)
        {
            <p class="text-muted"><span class="spinner-border spinner-border-sm me-1"></span>Loading…</p>
        }
-        else if (_tags.Count == 0)
+        else if (_refs.Count == 0)
        {
-            <p class="text-muted">No tags yet.</p>
+            <p class="text-muted">No tag references yet.</p>
        }
        else
        {
-            <table class="table table-sm">
+            <table class="table table-sm align-middle">
                <thead>
-                    <tr><th>Name</th><th>Driver</th><th>Data type</th><th>Access</th><th class="text-end">Actions</th></tr>
+                    <tr>
+                        <th>Effective name</th><th>Raw path</th><th>Data type</th><th>Access</th>
+                        <th>Display-name override</th><th class="text-end">Actions</th>
+                    </tr>
                </thead>
                <tbody>
-                    @foreach (var t in _tags)
+                    @foreach (var r in _refs)
                    {
-                        <tr @key="t.TagId">
-                            <td>@t.Name</td>
-                            <td class="mono">@t.DriverInstanceId</td>
-                            <td>@t.DataType</td>
-                            <td>@t.AccessLevel</td>
-                            <td class="text-end">
-                                <button type="button" class="btn btn-outline-secondary btn-sm me-1" @onclick="() => OpenEditTag(t.TagId)">Edit</button>
-                                <button type="button" class="btn btn-outline-danger btn-sm" @onclick="() => DeleteTag(t.TagId)">Delete</button>
+                        <tr @key="r.UnsTagReferenceId">
+                            <td>@r.EffectiveName</td>
+                            <td class="mono small">@r.RawPath</td>
+                            <td>@r.DataType</td>
+                            <td>@r.AccessLevel</td>
+                            <td>
+                                <input class="form-control form-control-sm" @bind="_overrideEdits[r.UnsTagReferenceId]"
+                                       placeholder="(uses raw name)" />
+                            </td>
+                            <td class="text-end text-nowrap">
+                                <button type="button" class="btn btn-outline-secondary btn-sm me-1" @onclick="() => SaveOverride(r)">Save name</button>
+                                <button type="button" class="btn btn-outline-danger btn-sm" @onclick="() => RemoveReference(r)">Remove</button>
                            </td>
                        </tr>
                    }
@@ -177,9 +179,8 @@ else
            </table>
        }

-        <TagModal Visible="_tagModalVisible" IsNew="_tagModalIsNew" EquipmentId="@EquipmentId"
-                  Existing="_tagModalExisting" Drivers="_tagDriverOptions"
-                  OnSaved="OnTagSavedAsync" OnCancel="@(() => { _tagModalVisible = false; })" />
+        <AddReferenceModal Visible="_refModalVisible" EquipmentId="@EquipmentId"
+                           OnCommitted="OnReferencesCommittedAsync" OnCancel="@(() => { _refModalVisible = false; })" />
    }
    else if (_activeTab == "vtags")
    {
@@ -290,15 +291,13 @@ else
    private EquipmentEditDto? _equipment;
    private FormModel _form = new();
    private IReadOnlyList<(string Id, string Display)> _lineOptions = Array.Empty<(string, string)>();
-    private IReadOnlyList<(string Id, string Display)> _driverOptions = Array.Empty<(string, string)>();

-    // --- Tags tab state. _tags is null until the tab is first activated (drives the lazy load + spinner). ---
-    private IReadOnlyList<EquipmentTagRow>? _tags;
-    private string? _tagError;
-    private bool _tagModalVisible;
-    private bool _tagModalIsNew;
-    private TagEditDto? _tagModalExisting;
-    private IReadOnlyList<(string Id, string Display, string DriverType, string DriverConfig)> _tagDriverOptions = Array.Empty<(string, string, string, string)>();
+    // --- Tags tab state (v3 reference-only). _refs is null until the tab is first activated (lazy load +
+    // spinner). _overrideEdits carries the per-row editable display-name override, keyed by reference id. ---
+    private IReadOnlyList<EquipmentReferenceRow>? _refs;
+    private readonly Dictionary<string, string?> _overrideEdits = new(StringComparer.Ordinal);
+    private string? _refError;
+    private bool _refModalVisible;

    // --- Virtual Tags tab state. _vtags is null until the tab is first activated. ---
    private IReadOnlyList<EquipmentVirtualTagRow>? _vtags;
@@ -329,54 +328,48 @@ else
    {
        _activeTab = tab;
        if (IsNew) { return; }
-        if (tab == "tags" && _tags is null) { await ReloadTagsAsync(); }
+        if (tab == "tags" && _refs is null) { await ReloadReferencesAsync(); }
        else if (tab == "vtags" && _vtags is null) { await ReloadVirtualTagsAsync(); }
        else if (tab == "alarms" && _alarms is null) { await ReloadAlarmsAsync(); }
    }

-    // --- Tags tab handlers (mirror GlobalUns; the owning equipment is fixed = EquipmentId) ---
+    // --- Tags tab handlers (v3 reference-only; the owning equipment is fixed = EquipmentId) ---

-    private async Task ReloadTagsAsync()
+    private async Task ReloadReferencesAsync()
    {
-        _tags = await Svc.LoadTagsForEquipmentAsync(EquipmentId!);
+        _refs = await Svc.LoadReferencesForEquipmentAsync(EquipmentId!);
+        // Seed the per-row override edit buffer so each row's <input> binds to a live value.
+        _overrideEdits.Clear();
+        foreach (var r in _refs) { _overrideEdits[r.UnsTagReferenceId] = r.DisplayNameOverride; }
    }

-    private async Task OpenAddTag()
+    private void OpenAddReference()
    {
-        _tagError = null;
-        _tagModalIsNew = true;
-        _tagModalExisting = null;
-        _tagDriverOptions = await Svc.LoadTagDriversForEquipmentAsync(EquipmentId!);
-        _tagModalVisible = true;
+        _refError = null;
+        _refModalVisible = true;
    }

-    private async Task OpenEditTag(string tagId)
+    private async Task OnReferencesCommittedAsync()
    {
-        _tagError = null;
-        var dto = await Svc.LoadTagAsync(tagId);
-        if (dto is null) { _tagError = "That tag no longer exists; the list was refreshed."; await ReloadTagsAsync(); return; }
-        _tagModalIsNew = false;
-        _tagModalExisting = dto;
-        _tagDriverOptions = await Svc.LoadTagDriversForEquipmentAsync(EquipmentId!);
-        _tagModalVisible = true;
+        _refModalVisible = false;
+        await ReloadReferencesAsync();
    }

-    private async Task OnTagSavedAsync()
+    private async Task SaveOverride(EquipmentReferenceRow r)
    {
-        _tagModalVisible = false;
-        await ReloadTagsAsync();
+        _refError = null;
+        var edited = _overrideEdits.GetValueOrDefault(r.UnsTagReferenceId);
+        var res = await Svc.SetReferenceOverrideAsync(r.UnsTagReferenceId, edited, r.RowVersion);
+        if (res.Ok) { await ReloadReferencesAsync(); }
+        else { _refError = res.Error; }
    }

-    private async Task DeleteTag(string tagId)
+    private async Task RemoveReference(EquipmentReferenceRow r)
    {
-        _tagModalVisible = false;
-        _tagError = null;
-        // Load the tag fresh to capture its current RowVersion for the optimistic-concurrency delete.
-        var dto = await Svc.LoadTagAsync(tagId);
-        if (dto is null) { await ReloadTagsAsync(); return; }
-        var r = await Svc.DeleteTagAsync(tagId, dto.RowVersion);
-        if (r.Ok) { await ReloadTagsAsync(); }
-        else { _tagError = r.Error; }
+        _refError = null;
+        var res = await Svc.RemoveReferenceAsync(r.UnsTagReferenceId, r.RowVersion);
+        if (res.Ok) { await ReloadReferencesAsync(); }
+        else { _refError = res.Error; }
    }

    // --- Virtual Tags tab handlers ---
@@ -478,7 +471,7 @@ else
        // path lands on Details because the field initializes to "details" and a fresh page instance
        // starts with that initial value. The Tags/Virtual Tags lists are reset to null below so the
        // lazy loaders re-fetch for the (possibly different) equipment this parameter set targets.
-        _tags = null;
+        _refs = null;
        _vtags = null;
        _alarms = null;
        if (!IsNew)
@@ -489,7 +482,6 @@ else
                LoadFormFrom(_equipment);
                var ctx = await Svc.LoadEquipmentPickContextAsync(_equipment.UnsLineId);
                _lineOptions = ctx.Lines;
-                _driverOptions = ctx.Drivers;
            }
        }
        else
@@ -497,7 +489,6 @@ else
            _form = new FormModel { UnsLineId = LineId ?? "" };
            var ctx = await Svc.LoadEquipmentPickContextAsync(LineId);
            _lineOptions = ctx.Lines;
-            _driverOptions = ctx.Drivers;
        }
        _loading = false;
    }
@@ -510,7 +501,6 @@ else
            Name = e.Name,
            MachineCode = e.MachineCode,
            UnsLineId = e.UnsLineId,
-            DriverInstanceId = e.DriverInstanceId,
            ZTag = e.ZTag,
            SAPID = e.SAPID,
            Manufacturer = e.Manufacturer,
@@ -536,7 +526,6 @@ else
                _form.Name,
                _form.MachineCode,
                _form.UnsLineId,
-                _form.DriverInstanceId,
                _form.ZTag,
                _form.SAPID,
                _form.Manufacturer,
@@ -582,7 +571,6 @@ else
        public string Name { get; set; } = "";
        [Required] public string MachineCode { get; set; } = "";
        [Required] public string UnsLineId { get; set; } = "";
-        public string? DriverInstanceId { get; set; }
        public string? ZTag { get; set; }
        public string? SAPID { get; set; }
        public string? Manufacturer { get; set; }
--- a/Show More
+++ b/Show More