Merge docs/track-deferred-items: track deferred work as issues; fix stale limitation

Claude-Session: https://claude.ai/code/session_01GASWkNEi68FSCtvr6rLoEW
docs: file Gitea issues for every deferred item; correct a stale limitation
2026-07-21 03:37:26 -04:00 · 2026-07-21 03:37:25 -04:00 · 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
227 changed files with 19285 additions and 4333 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.
@@ -217,6 +271,10 @@ The AdminUI's global **UNS** page (`/uns`) is the single surface for managing th

 **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
@@ -357,11 +415,16 @@ The `AlarmHistorian` section's old Wonderware connection keys (`Host`/`Port`/`Us
 were pruned — remove them; the SQLite knobs are retained and the downstream connection now comes from
 `ServerHistorian`. See `docs/Historian.md` for the full guide.

-### KNOWN LIMITATION 1 — live-validation gate (do before merging/trusting the cutover)
+### Live-validation gate — PASSED (was "KNOWN LIMITATION 1")

-The cutover is code-complete but **must be live-validated against a real gateway** (VPN to
-`wonder-sql-vd03`, gateway running the prerequisites above) before it is merged or trusted. Run the
-env-gated suite:
+**No longer a limitation.** The cutover was live-validated against the real gateway on
+`wonder-sql-vd03`: read ✅, write-persist ✅, alarm-send ✅, alarm-readback skipped as a *confirmed
+protocol limitation* (the captured `CM_EVENT` wire never carries `SourceName`, so the gateway cannot
+populate `Source_Object` — not a fixable bug). Evidence:
+`docs/plans/2026-06-27-otopcua-historian-followups.md`.
+
+Kept here because it is the recipe to **re-run** the gate after any gateway or backend change (VPN to
+`wonder-sql-vd03`, gateway running the prerequisites above):

 ```bash
 export HISTGW_GATEWAY_ENDPOINT=https://wonder-sql-vd03:5222   # absolute gateway URI; absent ⇒ all live tests skip
@@ -376,7 +439,7 @@ dotnet test --filter "Category=LiveIntegration"
 The live suite **skips cleanly** when these env vars are absent (safe to run offline on macOS). It is the
 gate the operator runs on the VPN before trusting the cutover.

-### KNOWN LIMITATION 2 — continuous-historization value-capture wired; live end-to-end verification still pending
+### KNOWN LIMITATION 2 — continuous-historization value-capture wired; live end-to-end verification still pending (issue #491)

 The `ContinuousHistorizationRecorder` is fully wired (actor + FasterLog outbox + gateway value-writer +
 meters). It is spawned with an **empty *initial* ref set** (`Array.Empty<string>()` in
@@ -390,4 +453,4 @@ deployed set of historized value tags from the first deploy onward (the feed is
 path is code-complete.** What remains is the **live gate**: an end-to-end verification against a real gateway
 (deploy → dependency-mux value delta → outbox append → `WriteLiveValues`) plus a restart-convergence test
 proving the recorder re-registers the deployed set after a process restart. Until that live verification runs,
-treat continuous value-capture as unproven-in-production rather than absent.
+treat continuous value-capture as unproven-in-production rather than absent. Tracked as **issue #491**.
@@ -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>
@@ -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
 ```
@@ -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,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,116 @@
+# 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). Filed as issue #487.**
+  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). Filed as issue #489.
+- Absolute-path Monaco completion → RawPath (from Batch 3; the `{{equip}}/` completion works). Filed as issue #490.
+- Cross-repo (post-merge): ScadaBridge Data-Connection-Layer NodeId/namespace cutover (raw `s=<RawPath>` /
+  UNS `s=<Area>/<Line>/<Equipment>/<EffectiveName>`, retired `EquipmentNodeIds`) — tracked in the
+  ScadaBridge repo as its issue #14 (its #20 landed the `nsu=` binding + native-alarm routing). The umbrella
+  index `../scadaproj/CLAUDE.md` OtOpcUa entry is **DONE** (scadaproj `ede5275`).
+
+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
@@ -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
 {
@@ -39,6 +39,7 @@ public static class DraftValidator
        ValidateRawNameCharset(draft, errors);
        ValidateHistorizedTagnameLength(draft, errors);
        ValidateUnsEffectiveLeafUniqueness(draft, errors);
+        ValidateEquipReferenceResolution(draft, errors);
        ValidateCalculationTags(draft, errors);
        return errors;
    }
@@ -238,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);

@@ -26,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>

@@ -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;
@@ -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>
@@ -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>
@@ -20,6 +20,7 @@
            <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>
@@ -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; }
@@ -29,6 +29,13 @@
    [Parameter] public bool ReadOnly { get; set; } = false;
    [Parameter] public bool ShowToolbar { get; set; } = true;

+    /// <summary>
+    /// Owning-equipment context for equipment-relative <c>{{equip}}/&lt;RefName&gt;</c> completion +
+    /// diagnostics. Set on the per-equipment VirtualTag / ScriptedAlarm modals; left null on the shared
+    /// ScriptEdit page (where the token cannot resolve to a single equipment).
+    /// </summary>
+    [Parameter] public string? EquipmentId { get; set; }
+
    /// <summary>
    /// Fires whenever Monaco's marker set updates (after the 500 ms diagnostic
    /// debounce). The marker DTO is not modelled yet — typed as object[] until a
@@ -61,7 +68,8 @@
                    {
                        value = Value ?? "",
                        language = Language,
-                        readOnly = ReadOnly
+                        readOnly = ReadOnly,
+                        equipmentId = EquipmentId
                    },
                    _dotNetRef);
                _initialized = true;
@@ -69,6 +69,28 @@
    /// </summary>
    [Parameter] public EventCallback OnRootsChanged { get; set; }

+    // ---------------------------------------------------------------------------
+    // v3 Batch 3 — raw-tag PICKER mode (opt-in; default off keeps the /raw usage byte-unchanged).
+    // In picker mode the mutation context-menus are suppressed: Tag leaves render a multi-select
+    // checkbox, and Device/TagGroup containers offer a "select all tags below" menu. The equipment
+    // page's "+ Add reference" modal drives this against a single cluster-scoped root.
+    // ---------------------------------------------------------------------------
+
+    /// <summary>When <c>true</c>, render the tree as a raw-tag picker (checkboxes + select-all) instead of
+    /// the editing tree. Default <c>false</c> — the /raw editing usage is unaffected.</summary>
+    [Parameter] public bool PickerMode { get; set; }
+
+    /// <summary>The shared, caller-owned set of selected raw <c>TagId</c>s (picker mode only). The component
+    /// mutates it in place and raises <see cref="OnSelectionChanged"/> after every change.</summary>
+    [Parameter] public HashSet<string>? SelectedTagIds { get; set; }
+
+    /// <summary>Raised after the selection set changes (picker mode) so the host can update its count / footer.</summary>
+    [Parameter] public EventCallback OnSelectionChanged { get; set; }
+
+    /// <summary>Supplies the raw <c>TagId</c>s beneath a Device/TagGroup node for the "select all tags below"
+    /// affordance (picker mode). The host wires this to <c>IUnsTreeService.LoadDescendantTagIdsAsync</c>.</summary>
+    [Parameter] public Func<RawNode, Task<IReadOnlyList<string>>>? ResolveDescendantTagIds { get; set; }
+
    // --- Configure-driver modal (edit) ---
    private bool _driverCfgVisible;
    private string? _driverCfgId;
@@ -198,6 +220,12 @@
    private RenderFragment RenderRowBody(RawNode node, bool muted) => __builder =>
    {
        <span class="d-inline-flex align-items-center gap-1">
+            @if (PickerMode && node.Kind == RawNodeKind.Tag)
+            {
+                <input type="checkbox" class="form-check-input me-1"
+                       checked="@IsTagSelected(node)"
+                       @onchange="@(e => ToggleTagSelection(node, e.Value is true))" />
+            }
            <span aria-hidden="true">@KindIcon(node.Kind)</span>
            <span class="mono small @(muted ? "text-muted" : "")">@node.DisplayName</span>
            @if (muted)
@@ -270,17 +298,67 @@
    // named handlers below are the seam Wave B/C replaces with the real modals.
    // ---------------------------------------------------------------------------

-    private IReadOnlyList<ContextMenuItem> MenuFor(RawNode node) => node.Kind switch
+    private IReadOnlyList<ContextMenuItem> MenuFor(RawNode node)
    {
-        RawNodeKind.Cluster  => ClusterMenu(node),
-        RawNodeKind.Folder   => FolderMenu(node),
-        RawNodeKind.Driver   => DriverMenu(node),
-        RawNodeKind.Device   => DeviceMenu(node),
-        RawNodeKind.TagGroup => TagGroupMenu(node),
-        RawNodeKind.Tag      => TagMenu(node),
-        _                    => Array.Empty<ContextMenuItem>(), // Enterprise: label only, no menu.
+        // Picker mode: no mutation menus. Device/TagGroup containers get a "select all tags below"
+        // affordance; every other kind (and Tag leaves, which carry the checkbox) has no menu.
+        if (PickerMode)
+        {
+            return node.Kind is RawNodeKind.Device or RawNodeKind.TagGroup
+                ? PickerContainerMenu(node)
+                : Array.Empty<ContextMenuItem>();
+        }
+
+        return node.Kind switch
+        {
+            RawNodeKind.Cluster  => ClusterMenu(node),
+            RawNodeKind.Folder   => FolderMenu(node),
+            RawNodeKind.Driver   => DriverMenu(node),
+            RawNodeKind.Device   => DeviceMenu(node),
+            RawNodeKind.TagGroup => TagGroupMenu(node),
+            RawNodeKind.Tag      => TagMenu(node),
+            _                    => Array.Empty<ContextMenuItem>(), // Enterprise: label only, no menu.
+        };
+    }
+
+    // --- Picker-mode menu + selection helpers ---
+
+    private List<ContextMenuItem> PickerContainerMenu(RawNode node) => new()
+    {
+        new() { Label = "Select all tags below", Icon = "☑", OnClick = () => SelectAllUnderAsync(node) },
+        new() { Label = "Clear all tags below", Icon = "☐", OnClick = () => ClearAllUnderAsync(node) },
    };

+    private bool IsTagSelected(RawNode node) =>
+        node.EntityId is not null && SelectedTagIds is not null && SelectedTagIds.Contains(node.EntityId);
+
+    private async Task ToggleTagSelection(RawNode node, bool selected)
+    {
+        if (SelectedTagIds is null || node.EntityId is null) { return; }
+        if (selected) { SelectedTagIds.Add(node.EntityId); }
+        else { SelectedTagIds.Remove(node.EntityId); }
+        await OnSelectionChanged.InvokeAsync();
+        StateHasChanged();
+    }
+
+    private async Task SelectAllUnderAsync(RawNode node)
+    {
+        if (SelectedTagIds is null || ResolveDescendantTagIds is null) { return; }
+        var ids = await ResolveDescendantTagIds(node);
+        foreach (var id in ids) { SelectedTagIds.Add(id); }
+        await OnSelectionChanged.InvokeAsync();
+        StateHasChanged();
+    }
+
+    private async Task ClearAllUnderAsync(RawNode node)
+    {
+        if (SelectedTagIds is null || ResolveDescendantTagIds is null) { return; }
+        var ids = await ResolveDescendantTagIds(node);
+        foreach (var id in ids) { SelectedTagIds.Remove(id); }
+        await OnSelectionChanged.InvokeAsync();
+        StateHasChanged();
+    }
+
    private List<ContextMenuItem> ClusterMenu(RawNode node) => new()
    {
        new() { Label = "New folder", Icon = "📁", OnClick = () => OnNewFolder(node) },
@@ -0,0 +1,125 @@
+@* v3 Batch 3 "+ Add reference" picker: reuses the Raw project tree (RawTree) in picker mode to
+   multi-select raw tags, scoped to the equipment's own cluster. The cluster scope is structural —
+   IUnsTreeService.LoadReferencePickerRootAsync hands back a SINGLE cluster root, so raw tags of any
+   other cluster are simply unreachable through the tree, not merely hidden. On commit the selected
+   tag ids are added as UnsTagReference rows via AddReferencesAsync; the host reloads its Tags list. *@
+@using ZB.MOM.WW.OtOpcUa.AdminUI.Uns
+@using ZB.MOM.WW.OtOpcUa.AdminUI.Components.Shared.Raw
+@inject IUnsTreeService Svc
+
+@if (Visible)
+{
+    <div class="modal-backdrop fade show" style="display:block"></div>
+    <div class="modal fade show" tabindex="-1" role="dialog" style="display:block">
+        <div class="modal-dialog modal-lg" role="document">
+            <div class="modal-content">
+                <div class="modal-header">
+                    <h5 class="modal-title">Add tag references</h5>
+                    <button type="button" class="btn-close" aria-label="Close" @onclick="CancelAsync"></button>
+                </div>
+                <div class="modal-body">
+                    <p class="text-muted small mb-2">
+                        Pick raw tags to reference under this equipment. The tree is scoped to the
+                        equipment's cluster. Tick individual tags, or use a device / tag-group's
+                        <em>“Select all tags below”</em> menu to pull many at once.
+                    </p>
+
+                    @if (_loading)
+                    {
+                        <p class="text-muted"><span class="spinner-border spinner-border-sm me-1"></span>Loading…</p>
+                    }
+                    else if (_roots.Count == 0)
+                    {
+                        <p class="text-muted">This equipment does not resolve to a cluster, so there are no raw tags to reference.</p>
+                    }
+                    else
+                    {
+                        <div class="border rounded p-2" style="max-height:50vh; overflow:auto">
+                            <RawTree Roots="_roots" PickerMode="true" SelectedTagIds="_selected"
+                                     OnSelectionChanged="OnSelectionChanged"
+                                     ResolveDescendantTagIds="ResolveDescendantsAsync" />
+                        </div>
+                    }
+
+                    @if (!string.IsNullOrWhiteSpace(_error))
+                    {
+                        <div class="text-danger small mt-2">@_error</div>
+                    }
+                </div>
+                <div class="modal-footer">
+                    <button type="button" class="btn btn-outline-secondary" @onclick="CancelAsync" disabled="@_busy">Cancel</button>
+                    <button type="button" class="btn btn-primary" @onclick="CommitAsync" disabled="@(_busy || _selected.Count == 0)">
+                        @if (_busy) { <span class="spinner-border spinner-border-sm me-1"></span> }
+                        Add @_selected.Count reference@(_selected.Count == 1 ? "" : "s")
+                    </button>
+                </div>
+            </div>
+        </div>
+    </div>
+}
+
+@code {
+    /// <summary>Whether the modal is shown. The host owns this flag.</summary>
+    [Parameter] public bool Visible { get; set; }
+
+    /// <summary>The equipment the selected raw tags are referenced under.</summary>
+    [Parameter] public string? EquipmentId { get; set; }
+
+    /// <summary>Raised after references are committed so the host can reload its Tags list and close.</summary>
+    [Parameter] public EventCallback OnCommitted { get; set; }
+
+    /// <summary>Raised when the user cancels so the host can close.</summary>
+    [Parameter] public EventCallback OnCancel { get; set; }
+
+    private IReadOnlyList<RawNode> _roots = Array.Empty<RawNode>();
+    private readonly HashSet<string> _selected = new(StringComparer.Ordinal);
+    private bool _busy;
+    private bool _loading;
+    private string? _error;
+    private bool _wasVisible;
+
+    protected override async Task OnParametersSetAsync()
+    {
+        // Reset + reload only on the false→true transition so re-renders while open don't wipe state.
+        if (Visible && !_wasVisible)
+        {
+            _selected.Clear();
+            _error = null;
+            _roots = Array.Empty<RawNode>();
+            _loading = true;
+            StateHasChanged();
+
+            var root = string.IsNullOrEmpty(EquipmentId)
+                ? null
+                : await Svc.LoadReferencePickerRootAsync(EquipmentId);
+            _roots = root is null ? Array.Empty<RawNode>() : new[] { root };
+            _loading = false;
+        }
+        _wasVisible = Visible;
+    }
+
+    private Task<IReadOnlyList<string>> ResolveDescendantsAsync(RawNode node) =>
+        Svc.LoadDescendantTagIdsAsync(node);
+
+    // RawTree mutates _selected in place; this just re-renders the footer count.
+    private void OnSelectionChanged() => StateHasChanged();
+
+    private async Task CommitAsync()
+    {
+        if (_selected.Count == 0) { return; }
+        _busy = true;
+        _error = null;
+        try
+        {
+            var res = await Svc.AddReferencesAsync(EquipmentId!, _selected.ToList());
+            if (res.Ok) { await OnCommitted.InvokeAsync(); }
+            else { _error = res.Error; }
+        }
+        finally
+        {
+            _busy = false;
+        }
+    }
+
+    private Task CancelAsync() => OnCancel.InvokeAsync();
+}
@@ -2,9 +2,10 @@
   the modal parses it into EquipmentInput rows and calls ImportEquipmentAsync, then shows the
   Inserted / Skipped / Errors summary in place. The host owns visibility; "Close" raises OnImported
   so the page can reload the whole tree (an import can add equipment across many lines/clusters).
-   Required header columns (in order): Name, MachineCode, UnsLineId, DriverInstanceId.
+   Required header columns (in order): Name, MachineCode, UnsLineId.
   Optional: ZTag, SAPID, Manufacturer, Model. Existing rows are detected by MachineCode and
-   skipped (additive-only — no updates), matching the retired /clusters/{id}/equipment/import page. *@
+   skipped (additive-only — no updates), matching the retired /clusters/{id}/equipment/import page.
+   v3: equipment no longer carries a driver, so the old DriverInstanceId column is gone. *@
@using ZB.MOM.WW.OtOpcUa.AdminUI.Uns
@inject IUnsTreeService Svc

@@ -21,7 +22,7 @@
                <div class="modal-body">
                    <p class="text-muted small mb-2">
                        Paste CSV below. Required header columns (in order):
-                        <span class="mono">Name, MachineCode, UnsLineId, DriverInstanceId</span>.
+                        <span class="mono">Name, MachineCode, UnsLineId</span>.
                        Optional: <span class="mono">ZTag, SAPID, Manufacturer, Model</span>.
                        Each row inserts one equipment with a freshly-generated EquipmentId. Existing rows
                        are detected by MachineCode and skipped (additive-only — no updates).
@@ -29,7 +30,7 @@

                    <textarea class="form-control form-control-sm mono" rows="12"
                              @bind="_csv" @bind:event="oninput" disabled="@_busy"
-                              placeholder="Name,MachineCode,UnsLineId,DriverInstanceId,ZTag,SAPID,Manufacturer,Model&#10;mixer-01,MX_001,LINE-1,drv-modbus-01,ZT-12345,SAP-9876,Siemens,SIMATIC-1500"></textarea>
+                              placeholder="Name,MachineCode,UnsLineId,ZTag,SAPID,Manufacturer,Model&#10;mixer-01,MX_001,LINE-1,ZT-12345,SAP-9876,Siemens,SIMATIC-1500"></textarea>
                    <div class="form-text">Simple comma-separated values only — fields containing commas are not supported.</div>

                    @if (!string.IsNullOrWhiteSpace(_parseError))
@@ -72,8 +73,8 @@
 }

@code {
-    // Required, in order; DriverInstanceId may be left blank per row (driver-less equipment).
-    private static readonly string[] RequiredColumns = ["Name", "MachineCode", "UnsLineId", "DriverInstanceId"];
+    // Required, in order. v3: equipment no longer binds a driver, so DriverInstanceId is gone.
+    private static readonly string[] RequiredColumns = ["Name", "MachineCode", "UnsLineId"];

    /// <summary>Whether the modal is shown. The host owns this flag.</summary>
    [Parameter] public bool Visible { get; set; }
@@ -133,7 +134,7 @@

    /// <summary>
    /// Parses the pasted CSV into <see cref="EquipmentInput"/> rows. Requires a header row whose first
-    /// four columns are Name, MachineCode, UnsLineId, DriverInstanceId (case-insensitive); the optional
+    /// three columns are Name, MachineCode, UnsLineId (case-insensitive); the optional
    /// ZTag/SAPID/Manufacturer/Model follow. Blank optional cells parse as <c>null</c>. Returns
    /// <c>null</c> (and sets <see cref="_parseError"/>) when the CSV is empty or the header is wrong.
    /// </summary>
@@ -169,11 +170,10 @@
                Name: parts[0],
                MachineCode: parts[1],
                UnsLineId: parts[2],
-                DriverInstanceId: NullIfEmpty(parts, 3),
-                ZTag: NullIfEmpty(parts, 4),
-                SAPID: NullIfEmpty(parts, 5),
-                Manufacturer: NullIfEmpty(parts, 6),
-                Model: NullIfEmpty(parts, 7),
+                ZTag: NullIfEmpty(parts, 3),
+                SAPID: NullIfEmpty(parts, 4),
+                Manufacturer: NullIfEmpty(parts, 5),
+                Model: NullIfEmpty(parts, 6),
                SerialNumber: null,
                HardwareRevision: null,
                SoftwareRevision: null,
@@ -1,557 +0,0 @@
-@* Create/edit modal for an equipment-bound tag, wired straight into IUnsTreeService. The host page
-   owns visibility and supplies the owning equipment id (create) or the loaded TagEditDto (edit), plus
-   the equipment-scoped candidate-driver list. Tree tags are always equipment-bound (decision #110), so
-   the legacy SystemPlatform/FolderPath branch is dropped entirely — there is no equipment selector
-   either, the owning equipment is fixed. On a successful save it raises OnSaved so the host can
-   refresh the equipment's children in place. *@
-@using System.ComponentModel.DataAnnotations
-@using System.Text.Json
-@using Microsoft.AspNetCore.Components.Forms
-@using ZB.MOM.WW.OtOpcUa.AdminUI.Uns
-@using ZB.MOM.WW.OtOpcUa.AdminUI.Uns.TagEditors
-@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.Enums
-@inject IUnsTreeService Svc
-
-@if (Visible)
-{
-    <div class="modal-backdrop fade show" style="display:block"></div>
-    <div class="modal fade show" tabindex="-1" role="dialog" style="display:block">
-        <div class="modal-dialog modal-lg" role="document">
-            <div class="modal-content">
-                <EditForm Model="_form" OnValidSubmit="SaveAsync" FormName="tagModal">
-                    <DataAnnotationsValidator />
-                    <div class="modal-header">
-                        <h5 class="modal-title">@(IsNew ? "New tag" : "Edit tag")</h5>
-                        <button type="button" class="btn-close" aria-label="Close" @onclick="CancelAsync"></button>
-                    </div>
-                    <div class="modal-body">
-                        <div class="row">
-                            <div class="col-md-6 mb-3">
-                                <label class="form-label" for="tag-id">TagId</label>
-                                <InputText id="tag-id" @bind-Value="_form.TagId" disabled="@(!IsNew)"
-                                           class="form-control form-control-sm mono"
-                                           placeholder="tag-line3-temp-01" />
-                                <ValidationMessage For="@(() => _form.TagId)" />
-                            </div>
-                            <div class="col-md-6 mb-3">
-                                <label class="form-label" for="tag-name">Name</label>
-                                <InputText id="tag-name" @bind-Value="_form.Name" class="form-control form-control-sm"
-                                           placeholder="Temperature setpoint" />
-                                <ValidationMessage For="@(() => _form.Name)" />
-                            </div>
-                        </div>
-                        <div class="row">
-                            <div class="col-md-6 mb-3">
-                                <label class="form-label" for="tag-driver">Driver instance</label>
-                                <InputSelect id="tag-driver" @bind-Value="_form.DriverInstanceId" @bind-Value:after="OnDriverChanged" class="form-select form-select-sm">
-                                    <option value="">— pick a driver —</option>
-                                    @foreach (var d in Drivers)
-                                    {
-                                        <option value="@d.Id">@d.Display</option>
-                                    }
-                                </InputSelect>
-                                <ValidationMessage For="@(() => _form.DriverInstanceId)" />
-                            </div>
-                            <div class="col-md-6 mb-3">
-                                <label class="form-label" for="tag-dtype">Data type</label>
-                                <InputSelect id="tag-dtype" @bind-Value="_form.DataType" class="form-select form-select-sm">
-                                    @foreach (var dt in DataTypes)
-                                    {
-                                        <option value="@dt">@dt</option>
-                                    }
-                                </InputSelect>
-                            </div>
-                        </div>
-                        <div class="row">
-                            <div class="col-md-6 mb-3">
-                                <label class="form-label" for="tag-access">Access level</label>
-                                <InputSelect id="tag-access" @bind-Value="_form.AccessLevel" class="form-select form-select-sm">
-                                    <option value="@TagAccessLevel.Read">Read</option>
-                                    <option value="@TagAccessLevel.ReadWrite">ReadWrite</option>
-                                </InputSelect>
-                            </div>
-                            <div class="col-md-6 mb-3">
-                                <label class="form-label">WriteIdempotent</label>
-                                <div class="form-check form-switch">
-                                    <InputCheckbox @bind-Value="_form.WriteIdempotent" class="form-check-input" />
-                                    <label class="form-check-label">Safe to retry writes (decision #44–45)</label>
-                                </div>
-                            </div>
-                        </div>
-                        <div class="mb-3">
-                            <label class="form-label" for="tag-pgroup">PollGroupId (optional)</label>
-                            <InputText id="tag-pgroup" @bind-Value="_form.PollGroupId" class="form-control form-control-sm mono" />
-                        </div>
-                        <div class="mb-3">
-                            <label class="form-label">Tag config</label>
-                            @{
-                                var editorType = TagConfigEditorMap.Resolve(SelectedDriverType);
-                            }
-                            @if (string.IsNullOrEmpty(_form.DriverInstanceId))
-                            {
-                                <div class="form-text">Pick a driver above to configure this tag.</div>
-                            }
-                            else if (IsGalaxyDriver)
-                            {
-                                @* GalaxyMxGateway has no typed TagConfigEditorMap editor; instead a Galaxy point is
-                                   authored as {"FullName":"tag_name.AttributeName"}. Offer the live-browse picker
-                                   (against the selected gateway's DriverConfig) plus a manual raw-JSON fallback. *@
-                                <button type="button" class="btn btn-outline-secondary btn-sm mb-2"
-                                        @onclick="@(() => _showGalaxyPicker = true)">
-                                    Browse Galaxy
-                                </button>
-                                <InputTextArea id="tag-config" @bind-Value="_form.TagConfig" rows="3"
-                                               class="form-control form-control-sm mono"
-                                               placeholder='{ "FullName": "DelmiaReceiver_001.DownloadPath" }' />
-                                <div class="form-text">
-                                    The Galaxy reference, stored as <code>{"FullName":"tag_name.AttributeName"}</code>.
-                                    Pick one via <strong>Browse Galaxy</strong> or edit the JSON directly.
-                                </div>
-
-                                @if (_showGalaxyPicker)
-                                {
-                                    <DriverTagPicker @bind-Visible="_showGalaxyPicker"
-                                                     Title="Galaxy address"
-                                                     CurrentAddress="@_galaxyAddress"
-                                                     OnPickAddress="@OnGalaxyAddressPicked">
-                                        <GalaxyAddressPickerBody CurrentAddress="@_galaxyAddress"
-                                                                 CurrentAddressChanged="@((s) => _galaxyAddress = s)"
-                                                                 @bind-SelectedIsAlarm="_galaxyPickedIsAlarm"
-                                                                 GetConfigJson="@(() => SelectedDriverConfig)" />
-                                    </DriverTagPicker>
-                                }
-                            }
-                            else if (editorType is not null)
-                            {
-                                <DynamicComponent Type="editorType" Parameters="BuildEditorParameters()" />
-                            }
-                            else
-                            {
-                                <InputTextArea id="tag-config" @bind-Value="_form.TagConfig" rows="6"
-                                               class="form-control form-control-sm mono"
-                                               placeholder='{ "register": 40001, "scale": 0.1 }' />
-                                <div class="form-text">Schemaless per driver type. Validated server-side at deploy.</div>
-                            }
-                            <ValidationMessage For="@(() => _form.TagConfig)" />
-                        </div>
-
-                        @* Driver-agnostic server-side HistoryRead intent. Distinct from the native-alarm
-                           "Historize to AVEVA" toggle below: THIS gates TAG-VALUE history (root keys
-                           `isHistorized` / `historianTagname`, read by AddressSpaceComposer.ExtractTagHistorize),
-                           merged onto the canonical TagConfig via the pure TagHistorizeConfig seam so it
-                           composes with the typed editor's driver-specific fields (both preserve unknown keys).
-                           Shown for EVERY driver once one is picked. *@
-                        @if (!string.IsNullOrEmpty(_form.DriverInstanceId))
-                        {
-                            <div class="mb-3">
-                                <label class="form-label">History</label>
-                                <div class="form-check form-switch">
-                                    <input class="form-check-input" type="checkbox" id="tag-historize"
-                                           checked="@_historizeState.IsHistorized"
-                                           @onchange="OnHistorizeChanged" />
-                                    <label class="form-check-label" for="tag-historize">Historize this tag (expose OPC UA HistoryRead)</label>
-                                </div>
-                                <div class="form-text">
-                                    When checked, the server serves OPC UA HistoryRead over this tag's value
-                                    from the configured historian.
-                                </div>
-                                @if (_historizeState.IsHistorized)
-                                {
-                                    <div class="mt-2">
-                                        <label class="form-label" for="tag-historian-tagname">Historian tagname (override, optional)</label>
-                                        <input type="text" class="form-control form-control-sm mono" id="tag-historian-tagname"
-                                               value="@_historizeState.HistorianTagname"
-                                               @onchange="OnHistorianTagnameChanged" />
-                                        <div class="form-text">Blank defaults the historian tagname to this tag's driver FullName.</div>
-                                    </div>
-                                }
-                            </div>
-                        }
-
-                        @* Driver-agnostic array-shape intent. Merges the root `isArray` / `arrayLength`
-                           keys onto the canonical TagConfig via the pure TagArrayConfig seam so it composes
-                           with the typed editor's driver-specific fields (both preserve unknown keys). When
-                           checked, the server materialises a 1-D array node (ValueRank=1). Shown for EVERY
-                           driver once one is picked — same place/pattern as the historize control above. *@
-                        @if (!string.IsNullOrEmpty(_form.DriverInstanceId))
-                        {
-                            <div class="mb-3">
-                                <label class="form-label">Array</label>
-                                <div class="form-check form-switch">
-                                    <input class="form-check-input" type="checkbox" id="tag-is-array"
-                                           checked="@_arrayState.IsArray"
-                                           @onchange="OnIsArrayChanged" />
-                                    <label class="form-check-label" for="tag-is-array">This tag is an array (1-D)</label>
-                                </div>
-                                <div class="form-text">
-                                    When checked, the server materialises this tag as a fixed-length 1-D array node.
-                                </div>
-                                @if (_arrayState.IsArray)
-                                {
-                                    <div class="mt-2">
-                                        <label class="form-label" for="tag-array-length">Array length</label>
-                                        <input type="number" min="1" step="1" class="form-control form-control-sm mono" id="tag-array-length"
-                                               value="@_arrayState.ArrayLength"
-                                               @onchange="OnArrayLengthChanged" />
-                                        <div class="form-text">Number of elements (must be a positive whole number).</div>
-                                    </div>
-                                }
-                            </div>
-                        }
-
-                        @* Native-alarm options: shown only when the TagConfig carries an `alarm` object (the tag
-                           is a Part 9 condition). The "Historize to AVEVA" toggle edits the alarm.historizeToAveva
-                           opt-out (bool?, unchecked-via-clear ⇒ absent ⇒ historize default-on at the server gate;
-                           explicit false suppresses the durable AVEVA write — same posture as scripted alarms). *@
-                        @if (HasNativeAlarm)
-                        {
-                            <div class="mb-3">
-                                <label class="form-label">Native alarm</label>
-                                <div class="form-check">
-                                    <input class="form-check-input" type="checkbox" id="tag-alarm-historize"
-                                           checked="@AlarmHistorizeToAveva"
-                                           @onchange="OnAlarmHistorizeChanged" />
-                                    <label class="form-check-label" for="tag-alarm-historize">Historize to AVEVA</label>
-                                </div>
-                                <div class="form-text">
-                                    When unchecked, this alarm's transitions are NOT written to the AVEVA historian
-                                    (the live alerts feed is unaffected). Checked is the default.
-                                </div>
-                            </div>
-                        }
-
-                        @if (!string.IsNullOrWhiteSpace(_error))
-                        {
-                            <div class="text-danger small mt-2">@_error</div>
-                        }
-                    </div>
-                    <div class="modal-footer">
-                        <button type="button" class="btn btn-outline-secondary" @onclick="CancelAsync" disabled="@_busy">Cancel</button>
-                        <button type="submit" class="btn btn-primary" disabled="@_busy">
-                            @if (_busy) { <span class="spinner-border spinner-border-sm me-1"></span> }
-                            @(IsNew ? "Create" : "Save changes")
-                        </button>
-                    </div>
-                </EditForm>
-            </div>
-        </div>
-    </div>
-}
-
-@code {
-    private static readonly string[] DataTypes =
-        ["Boolean", "SByte", "Byte", "Int16", "UInt16", "Int32", "UInt32",
-         "Int64", "UInt64", "Float", "Double", "String", "DateTime", "Guid", "ByteString"];
-
-    /// <summary>Whether the modal is shown. The host owns this flag.</summary>
-    [Parameter] public bool Visible { get; set; }
-
-    /// <summary><c>true</c> to create a new tag; <c>false</c> to edit <see cref="Existing"/>.</summary>
-    [Parameter] public bool IsNew { get; set; }
-
-    /// <summary>The owning equipment id the created tag binds to (used only on create).</summary>
-    [Parameter] public string? EquipmentId { get; set; }
-
-    /// <summary>The tag being edited, when <see cref="IsNew"/> is <c>false</c>.</summary>
-    [Parameter] public TagEditDto? Existing { get; set; }
-
-    /// <summary>The candidate drivers — scoped to the equipment's cluster by the host — as
-    /// <c>(Id, Display, DriverType, DriverConfig)</c> tuples. <c>DriverType</c> drives typed-editor dispatch;
-    /// <c>DriverConfig</c> feeds the Galaxy live-browse picker for GalaxyMxGateway drivers.</summary>
-    [Parameter] public IReadOnlyList<(string Id, string Display, string DriverType, string DriverConfig)> Drivers { get; set; } = Array.Empty<(string, string, string, string)>();
-
-    /// <summary>Raised after a successful create/save so the host can refresh the equipment's children and close.</summary>
-    [Parameter] public EventCallback OnSaved { get; set; }
-
-    /// <summary>Raised when the user cancels so the host can close.</summary>
-    [Parameter] public EventCallback OnCancel { get; set; }
-
-    private FormModel _form = new();
-    private bool _busy;
-    private string? _error;
-
-    // Galaxy live-browse picker state. Only meaningful when the selected driver is a GalaxyMxGateway.
-    private bool _showGalaxyPicker;
-    private string _galaxyAddress = "";
-
-    // True when the attribute most-recently selected in the Galaxy picker is itself an alarm
-    // (DriverAttributeInfo.IsAlarm). On commit, this pre-fills a default native-alarm object into the
-    // TagConfig (when none is present) so the operator can author the alarm in one pass.
-    private bool _galaxyPickedIsAlarm;
-
-    // Driver-agnostic server-side HistoryRead intent (root `isHistorized` / `historianTagname`), reflected
-    // for the "Historize this tag" controls. Re-read from _form.TagConfig whenever the modal (re)opens or
-    // the driver changes; the change handlers merge it back onto _form.TagConfig via TagHistorizeConfig.
-    private TagHistorizeConfig.HistorizeState _historizeState;
-
-    // Driver-agnostic array-shape intent (root `isArray` / `arrayLength`), reflected for the array controls.
-    // Re-read from _form.TagConfig whenever the modal (re)opens or the driver changes; the change handlers
-    // merge it back onto _form.TagConfig via TagArrayConfig (same pattern as _historizeState above).
-    private TagArrayConfig.ArrayState _arrayState;
-
-    // The DriverType of the currently-selected driver (drives editor dispatch). Null when no driver chosen.
-    private string? SelectedDriverType =>
-        Drivers.FirstOrDefault(d => d.Id == _form.DriverInstanceId).DriverType;
-
-    // The DriverConfig JSON of the currently-selected driver — fed to the Galaxy picker so it browses the
-    // right gateway. Defaults to "{}" when no driver is chosen or the config is empty.
-    private string SelectedDriverConfig
-    {
-        get
-        {
-            var cfg = Drivers.FirstOrDefault(d => d.Id == _form.DriverInstanceId).DriverConfig;
-            return string.IsNullOrEmpty(cfg) ? "{}" : cfg;
-        }
-    }
-
-    // True when the selected driver is a GalaxyMxGateway — Galaxy points are authored as
-    // {"FullName":"tag_name.AttributeName"} via the live-browse picker rather than a typed editor.
-    private bool IsGalaxyDriver => SelectedDriverType == "GalaxyMxGateway";
-
-    // When the operator switches drivers, the previous driver's TagConfig schema no longer applies —
-    // reset it so the newly-dispatched typed editor starts clean (no stale/leaked keys from the old
-    // driver). Fires only on a user dropdown change (@bind-Value:after), not on the initial edit-load.
-    private void OnDriverChanged()
-    {
-        _form.TagConfig = "{}";
-        // The Galaxy reference belongs to the previous driver; clear the picker's working address too.
-        _galaxyAddress = "";
-        _galaxyPickedIsAlarm = false;
-        // The reset TagConfig carries no history intent — reflect that in the historize controls.
-        _historizeState = TagHistorizeConfig.Read(_form.TagConfig);
-        // Likewise the reset TagConfig carries no array intent.
-        _arrayState = TagArrayConfig.Read(_form.TagConfig);
-    }
-
-    // The operator picked a Galaxy reference (tag_name.AttributeName); store it as the canonical
-    // {"FullName":"..."} TagConfig the Galaxy driver resolves to an MXAccess reference. Default
-    // (PascalCase) serialization yields the "FullName" key the driver/walker reads.
-    //
-    // When the picked attribute is itself an alarm (DriverAttributeInfo.IsAlarm), pre-seed a default
-    // native-alarm `alarm` object so the tag materialises as a Part 9 condition and Task 3's
-    // "Historize to AVEVA" toggle auto-appears — sparing the operator hand-written JSON. NativeAlarmModel
-    // .SeedDefaultAlarm only seeds when absent (never overwrites an authored alarm) and preserves FullName.
-    private void OnGalaxyAddressPicked(string address)
-    {
-        _galaxyAddress = address;
-        // Re-picking a Galaxy address owns ONLY the address-derived FullName key — apply it over the EXISTING
-        // TagConfig so every other user-edited field survives verbatim. This preserves a hand-authored `alarm`
-        // object (FB-4: a re-pick must never clobber edited alarm fields) as well as the root history/array
-        // intent and any driver/unknown keys. TagConfigJson.SetFullName uses the same preserve-unknown idiom
-        // as the historize/array merge seams.
-        var config = TagConfigJson.SetFullName(_form.TagConfig, address);
-        _form.TagConfig = _galaxyPickedIsAlarm
-            ? NativeAlarmModel.SeedDefaultAlarm(config)
-            : config;
-        _historizeState = TagHistorizeConfig.Read(_form.TagConfig);
-        _arrayState = TagArrayConfig.Read(_form.TagConfig);
-    }
-
-    private IDictionary<string, object> BuildEditorParameters() => new Dictionary<string, object>
-    {
-        ["ConfigJson"] = _form.TagConfig,
-        ["ConfigJsonChanged"] = EventCallback.Factory.Create<string>(this, v => _form.TagConfig = v),
-        ["DriverType"] = SelectedDriverType ?? "",
-        ["GetDriverConfigJson"] = (Func<string>)(() => SelectedDriverConfig),
-    };
-
-    // Cache a single NativeAlarmModel parse keyed on the current TagConfig string, so the two computed
-    // properties below don't each re-parse the JSON on every render. Re-parsed only when TagConfig changes.
-    private NativeAlarmModel _nativeAlarm = NativeAlarmModel.FromJson("{}");
-    private string? _nativeAlarmSource;
-
-    private NativeAlarmModel NativeAlarm
-    {
-        get
-        {
-            if (_nativeAlarmSource != _form.TagConfig)
-            {
-                _nativeAlarmSource = _form.TagConfig;
-                _nativeAlarm = NativeAlarmModel.FromJson(_form.TagConfig);
-            }
-            return _nativeAlarm;
-        }
-    }
-
-    // True when the current TagConfig carries an `alarm` object — i.e. the tag is materialised as a Part 9
-    // native-alarm condition rather than a value variable. Gates the "Historize to AVEVA" toggle's visibility.
-    private bool HasNativeAlarm => NativeAlarm.IsAlarm;
-
-    // The native alarm's HistorizeToAveva intent reflected for the checkbox: absent (null) ⇒ historize
-    // (default-on at the server gate), so the box is checked for both null and explicit true; only an
-    // explicit false leaves it unchecked.
-    private bool AlarmHistorizeToAveva => NativeAlarm.HistorizeToAveva != false;
-
-    // Toggle the alarm.historizeToAveva opt-out in the raw TagConfig. Checked ⇒ remove the key (null ⇒
-    // absent ⇒ historize default-on); unchecked ⇒ write an explicit false (suppress the durable AVEVA row).
-    // Unknown keys at the root + inside `alarm` are preserved across the edit (NativeAlarmModel round-trip).
-    private void OnAlarmHistorizeChanged(ChangeEventArgs e)
-    {
-        var model = NativeAlarmModel.FromJson(_form.TagConfig);
-        if (!model.IsAlarm) { return; }
-        model.HistorizeToAveva = e.Value is true ? null : false;
-        _form.TagConfig = model.ToJson();
-    }
-
-    // Toggle the root `isHistorized` tag-value history intent in the raw TagConfig, merged via the pure
-    // TagHistorizeConfig seam so the typed editor's driver-specific keys are preserved. Distinct from the
-    // native-alarm "Historize to AVEVA" opt-out above (that gates alarm-transition history, not tag values).
-    private void OnHistorizeChanged(ChangeEventArgs e)
-    {
-        var isHistorized = e.Value is true;
-        _form.TagConfig = TagHistorizeConfig.Set(_form.TagConfig, isHistorized, _historizeState.HistorianTagname);
-        _historizeState = TagHistorizeConfig.Read(_form.TagConfig);
-    }
-
-    // Merge the optional historian-tagname override (root `historianTagname`) into the raw TagConfig.
-    private void OnHistorianTagnameChanged(ChangeEventArgs e)
-    {
-        var tagname = e.Value?.ToString() ?? string.Empty;
-        _form.TagConfig = TagHistorizeConfig.Set(_form.TagConfig, _historizeState.IsHistorized, tagname);
-        _historizeState = TagHistorizeConfig.Read(_form.TagConfig);
-    }
-
-    // Toggle the root `isArray` array-shape intent in the raw TagConfig, merged via the pure TagArrayConfig
-    // seam so the typed editor's driver-specific keys are preserved. Clearing it drops `arrayLength` too
-    // (no orphan length), so the carried _arrayState.ArrayLength is irrelevant when unchecking.
-    private void OnIsArrayChanged(ChangeEventArgs e)
-    {
-        var isArray = e.Value is true;
-        _form.TagConfig = TagArrayConfig.Set(_form.TagConfig, isArray, _arrayState.ArrayLength);
-        _arrayState = TagArrayConfig.Read(_form.TagConfig);
-    }
-
-    // Merge the array length (root `arrayLength`) into the raw TagConfig. A blank/zero/negative/non-numeric
-    // entry parses to null, so the key is dropped until a positive length is typed (and SaveAsync rejects
-    // an array with no positive length).
-    private void OnArrayLengthChanged(ChangeEventArgs e)
-    {
-        var length = ParsePositiveLength(e.Value?.ToString());
-        _form.TagConfig = TagArrayConfig.Set(_form.TagConfig, _arrayState.IsArray, length);
-        _arrayState = TagArrayConfig.Read(_form.TagConfig);
-    }
-
-    // Parse the numeric-input string to a positive uint, or null for blank/zero/negative/overflow/non-numeric.
-    private static uint? ParsePositiveLength(string? raw)
-        => uint.TryParse(raw, out var u) && u > 0 ? u : null;
-
-    protected override void OnParametersSet()
-    {
-        // Rebuild the working form whenever the host (re)opens the modal for a fresh target.
-        if (IsNew)
-        {
-            _form = new FormModel();
-        }
-        else if (Existing is not null)
-        {
-            _form = new FormModel
-            {
-                TagId = Existing.TagId,
-                Name = Existing.Name,
-                DriverInstanceId = Existing.DriverInstanceId,
-                DataType = Existing.DataType,
-                AccessLevel = Existing.AccessLevel,
-                WriteIdempotent = Existing.WriteIdempotent,
-                PollGroupId = Existing.PollGroupId,
-                TagConfig = Existing.TagConfig,
-            };
-        }
-        _error = null;
-        _showGalaxyPicker = false;
-        _galaxyPickedIsAlarm = false;
-        // Seed the picker's working address from any existing {"FullName":"..."} so it opens pre-populated.
-        _galaxyAddress = ReadFullName(_form.TagConfig);
-        // Seed the historize controls from any existing root isHistorized/historianTagname keys.
-        _historizeState = TagHistorizeConfig.Read(_form.TagConfig);
-        // Seed the array controls from any existing root isArray/arrayLength keys.
-        _arrayState = TagArrayConfig.Read(_form.TagConfig);
-    }
-
-    // Best-effort extraction of FullName from a Galaxy TagConfig; returns "" when absent or unparseable.
-    private static string ReadFullName(string? configJson)
-    {
-        if (string.IsNullOrWhiteSpace(configJson)) return "";
-        try
-        {
-            using var doc = JsonDocument.Parse(configJson);
-            return doc.RootElement.ValueKind == JsonValueKind.Object
-                   && doc.RootElement.TryGetProperty("FullName", out var fn)
-                   && fn.ValueKind == JsonValueKind.String
-                ? fn.GetString() ?? ""
-                : "";
-        }
-        catch (JsonException)
-        {
-            return "";
-        }
-    }
-
-    private async Task SaveAsync()
-    {
-        _busy = true;
-        _error = null;
-        try
-        {
-            // Client-side per-driver config validation (the typed editor's Validate()), so a blank
-            // required field is caught here rather than silently saving and failing at deploy/connect.
-            var configError = TagConfigValidator.Validate(SelectedDriverType, _form.TagConfig);
-            if (configError is not null)
-            {
-                _error = configError;
-                return;
-            }
-
-            // Driver-agnostic array-shape validation: an array tag needs a positive length. Mirrors the
-            // per-driver config validation above so a missing length is caught here rather than at deploy.
-            var arrayError = TagArrayConfig.Validate(_arrayState.IsArray, _arrayState.ArrayLength);
-            if (arrayError is not null)
-            {
-                _error = arrayError;
-                return;
-            }
-
-            var input = new TagInput(
-                _form.TagId,
-                _form.Name,
-                _form.DriverInstanceId,
-                _form.DataType,
-                _form.AccessLevel,
-                _form.WriteIdempotent,
-                _form.PollGroupId,
-                _form.TagConfig);
-
-            var result = IsNew
-                ? await Svc.CreateTagAsync(EquipmentId!, input)
-                : await Svc.UpdateTagAsync(Existing!.TagId, input, Existing.RowVersion);
-
-            if (result.Ok)
-            {
-                await OnSaved.InvokeAsync();
-            }
-            else
-            {
-                _error = result.Error;
-            }
-        }
-        finally
-        {
-            _busy = false;
-        }
-    }
-
-    private Task CancelAsync() => OnCancel.InvokeAsync();
-
-    private sealed class FormModel
-    {
-        [Required, RegularExpression("^[A-Za-z0-9_-]+$")] public string TagId { get; set; } = "";
-        [Required] public string Name { get; set; } = "";
-        [Required] public string DriverInstanceId { get; set; } = "";
-        public string DataType { get; set; } = "Float";
-        public TagAccessLevel AccessLevel { get; set; } = TagAccessLevel.Read;
-        public bool WriteIdempotent { get; set; }
-        public string? PollGroupId { get; set; }
-        [Required] public string TagConfig { get; set; } = "{}";
-    }
-}
@@ -99,7 +99,7 @@
                                            Editing shared script "<span class="mono">@_scriptName</span>" — used by
                                            @_scriptUsageCount virtual tag(s). Changes affect all of them.
                                        </div>
-                                        <MonacoEditor @bind-Value="_scriptSource" Height="300px" />
+                                        <MonacoEditor @bind-Value="_scriptSource" Height="300px" EquipmentId="@EquipmentId" />
                                        @if (!string.IsNullOrWhiteSpace(_scriptError))
                                        {
                                            <div class="text-danger small mt-2">@_scriptError</div>
@@ -1,3 +1,4 @@
+using Microsoft.AspNetCore.Authorization;
 using Microsoft.AspNetCore.Builder;
 using Microsoft.AspNetCore.Components;
 using Microsoft.AspNetCore.Components.Web;
@@ -10,6 +11,7 @@ using ZB.MOM.WW.OtOpcUa.Commons.Browsing;
 using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
 using ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Browser;
 using ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient.Browser;
+using ZB.MOM.WW.Secrets.Ui;

 namespace ZB.MOM.WW.OtOpcUa.AdminUI;

@@ -28,6 +30,12 @@ public static class EndpointRouteBuilderExtensions
        // Razor class library static assets (_content/ZB.MOM.WW.OtOpcUa.AdminUI/**) are
        // served via the Host's app.UseStaticFiles() middleware which must run BEFORE
        // UseAuthentication() — see Program.cs.
+        // The Secrets.Ui RCL's routable page is deliberately NOT registered here (lmxopcua#483):
+        // this host's router is static with per-page @rendermode opt-in, so routing straight to
+        // the RCL page rendered it without a circuit — it displayed but every @onclick was dead.
+        // Pages/Secrets.razor in THIS assembly owns /admin/secrets instead (wrapping the RCL
+        // page with the render mode); registering the RCL routes too would make the route
+        // ambiguous.
        app.MapRazorComponents<TApp>()
            .AddInteractiveServerRenderMode();
        return app;
@@ -43,12 +51,25 @@ public static class EndpointRouteBuilderExtensions
        services.AddRazorComponents().AddInteractiveServerComponents();
        services.AddOtOpcUaDriverStatusServices();

+        // Secrets-management UI (ZB.MOM.WW.Secrets.Ui RCL, mounted at /admin/secrets). Register its
+        // "secrets:manage"/"secrets:reveal" authorization policies additively onto the AuthorizationOptions
+        // that AddOtOpcUaAuth (called just before AddAdminUI on admin nodes) sets up — Configure<T> stacks,
+        // so this ADDS the two policies without disturbing FleetAdmin/DriverOperator/ConfigEditor. The
+        // policies' AdminRole = "Administrator" reads the same ClaimTypes.Role claim as FleetAdmin, so an
+        // existing Administrator satisfies them with no new group→role mapping. Registered here (the AdminUI
+        // composition layer that already references the RCL) rather than in the core Security lib.
+        services.Configure<AuthorizationOptions>(o => o.AddSecretsAuthorization());
+
        // Browse pipeline — see docs/plans/2026-05-28-driver-browsers-design.md
        services.AddSingleton<Browsing.BrowseSessionRegistry>();
        services.AddHostedService<Browsing.BrowseSessionReaper>();
        services.AddScoped<Browsing.IBrowserSessionService, Browsing.BrowserSessionService>();
        services.AddScoped<IUnsTreeService, UnsTreeService>();
        services.AddScoped<IRawTreeService, RawTreeService>();
+        // v3 Batch 3 (WP2): authoring-time UNS effective-name uniqueness guard. Consumed by
+        // UnsTreeService's reference/VirtualTag/ScriptedAlarm mutations (WP1); mirrors the
+        // deploy-time DraftValidator UnsEffectiveNameCollision rule.
+        services.AddScoped<IEffectiveNameGuard, EffectiveNameGuard>();
        // WP5 CSV export enumeration (read-only; does not extend the closed IRawTreeService prelude).
        services.AddScoped<RawTagCsvExportReader>();
        services.AddSingleton<IDriverBrowser, OpcUaClientDriverBrowser>();
@@ -23,13 +23,16 @@ public interface IScriptTagCatalog
    /// <returns>The resolved tag info, or <see langword="null"/> when <paramref name="path"/> is not a known configured path.</returns>
    Task<ScriptTagInfo?> GetTagInfoAsync(string path, CancellationToken ct);

-    /// <summary>Distinct attribute leaf names — the substring after the first dot of each
-    /// configured tag FullName — optionally prefix-filtered. Powers {{equip}}. completion,
-    /// which needs the per-equipment object prefix stripped.</summary>
-    /// <param name="filter">Case-insensitive StartsWith prefix over the leaf; null/empty = all (bounded).</param>
+    /// <summary>v3: the owning equipment's <c>UnsTagReference</c> effective names (its
+    /// <c>DisplayNameOverride</c> else the backing raw tag's <c>Name</c>) — the resolvable set for
+    /// <c>{{equip}}/&lt;RefName&gt;</c> completion + diagnostics, matching what the compose seams substitute
+    /// and the deploy gate enforces. Optionally prefix-filtered. Empty when the equipment id is blank or has
+    /// no references.</summary>
+    /// <param name="equipmentId">The equipment whose references to list; blank returns empty.</param>
+    /// <param name="filter">Case-insensitive StartsWith prefix over the reference name; null/empty = all (bounded).</param>
    /// <param name="ct">Cancellation token.</param>
-    /// <returns>Distinct leaf names.</returns>
-    Task<IReadOnlyList<string>> GetEquipmentRelativeLeavesAsync(string? filter, CancellationToken ct);
+    /// <returns>Distinct reference effective names.</returns>
+    Task<IReadOnlyList<string>> GetEquipmentReferenceNamesAsync(string equipmentId, string? filter, CancellationToken ct);
 }

 /// <summary>Resolved info for one configured tag/virtual-tag path (for hover).</summary>
@@ -114,17 +117,32 @@ public sealed class ScriptTagCatalog(IDbContextFactory<OtOpcUaConfigDbContext> d
    }

    /// <inheritdoc />
-    public async Task<IReadOnlyList<string>> GetEquipmentRelativeLeavesAsync(string? filter, CancellationToken ct)
+    public async Task<IReadOnlyList<string>> GetEquipmentReferenceNamesAsync(string equipmentId, string? filter, CancellationToken ct)
    {
-        var entries = await BuildEntriesAsync(ct);
-        var leaves = new HashSet<string>(StringComparer.Ordinal);
-        foreach (var e in entries)
+        if (string.IsNullOrEmpty(equipmentId)) return Array.Empty<string>();
+        await using var db = await dbFactory.CreateDbContextAsync(ct);
+
+        var refs = await db.UnsTagReferences.AsNoTracking()
+            .Where(r => r.EquipmentId == equipmentId)
+            .Select(r => new { r.TagId, r.DisplayNameOverride })
+            .ToListAsync(ct);
+        if (refs.Count == 0) return Array.Empty<string>();
+
+        var tagIds = refs.Select(r => r.TagId).Distinct().ToList();
+        var tagNameById = await db.Tags.AsNoTracking()
+            .Where(t => tagIds.Contains(t.TagId))
+            .Select(t => new { t.TagId, t.Name })
+            .ToDictionaryAsync(t => t.TagId, t => t.Name, ct);
+
+        // Effective name = DisplayNameOverride else the backing raw tag's Name (ordinal set).
+        var names = new HashSet<string>(StringComparer.Ordinal);
+        foreach (var r in refs)
        {
-            var dot = e.Path.IndexOf('.');
-            if (dot < 0 || dot + 1 >= e.Path.Length) continue;
-            leaves.Add(e.Path.Substring(dot + 1));
+            var eff = r.DisplayNameOverride ?? (tagNameById.TryGetValue(r.TagId, out var n) ? n : null);
+            if (!string.IsNullOrEmpty(eff)) names.Add(eff!);
        }
-        IEnumerable<string> q = leaves;
+
+        IEnumerable<string> q = names;
        if (!string.IsNullOrWhiteSpace(filter))
            q = q.Where(n => n.StartsWith(filter, StringComparison.OrdinalIgnoreCase));
        return q.OrderBy(n => n, StringComparer.OrdinalIgnoreCase).Take(MaxResults).ToList();
@@ -1,15 +1,19 @@
 namespace ZB.MOM.WW.OtOpcUa.AdminUI.ScriptAnalysis;

-public record DiagnoseRequest(string Code);
+// EquipmentId (optional) carries the owning-equipment context the {{equip}}/<RefName> completion +
+// diagnostic need to resolve reference effective names. Null on the shared ScriptEdit page (no single
+// equipment) — the equip-ref features are then inert, matching the deploy gate (which only resolves per
+// owning equipment).
+public record DiagnoseRequest(string Code, string? EquipmentId = null);
 public record DiagnoseResponse(IReadOnlyList<DiagnosticMarker> Markers);
 public record DiagnosticMarker(int Severity, int StartLineNumber, int StartColumn,
    int EndLineNumber, int EndColumn, string Message, string Code);

-public record CompletionsRequest(string CodeText, int Line, int Column);
+public record CompletionsRequest(string CodeText, int Line, int Column, string? EquipmentId = null);
 public record CompletionsResponse(IReadOnlyList<CompletionItem> Items);
 public record CompletionItem(string Label, string InsertText, string Detail, string Kind, int InsertTextRules = 0);

-public record HoverRequest(string CodeText, int Line, int Column);
+public record HoverRequest(string CodeText, int Line, int Column, string? EquipmentId = null);
 public record HoverResponse(string? Markdown);

 public record SignatureHelpRequest(string CodeText, int Line, int Column);
@@ -16,7 +16,7 @@ public static class ScriptAnalysisEndpoints
        // ConfigEditor policy (Administrator or Designer) — matches the Script page gate and the /deployments gate.
        var group = endpoints.MapGroup("/api/script-analysis")
            .RequireAuthorization(AdminUiPolicies.ConfigEditor);
-        group.MapPost("/diagnostics",    (DiagnoseRequest r, ScriptAnalysisService s) => Results.Ok(s.Diagnose(r)));
+        group.MapPost("/diagnostics",    async (DiagnoseRequest r, ScriptAnalysisService s) => Results.Ok(await s.DiagnoseAsync(r)));
        group.MapPost("/completions",    async (CompletionsRequest r, ScriptAnalysisService s) => Results.Ok(await s.CompleteAsync(r)));
        group.MapPost("/hover",          async (HoverRequest r, ScriptAnalysisService s) => Results.Ok(await s.Hover(r)));
        group.MapPost("/signature-help", (SignatureHelpRequest r, ScriptAnalysisService s) => Results.Ok(s.SignatureHelp(r)));
@@ -130,6 +130,58 @@ public sealed class ScriptAnalysisService
        }
    }

+    // ctx.GetTag("…") / ctx.SetVirtualTag("…") first-arg literal — three-part capture, mirroring
+    // EquipmentScriptPaths.PathLiteralRegex so the editor's {{equip}}/<RefName> diagnostic is scoped to the
+    // SAME path literals the compose seams substitute (never a comment / logger string).
+    private static readonly System.Text.RegularExpressions.Regex EquipPathLiteralRegex =
+        new(@"(ctx\s*\.\s*(?:GetTag|SetVirtualTag)\s*\(\s*"")([^""]*)("")",
+            System.Text.RegularExpressions.RegexOptions.Compiled);
+
+    /// <summary>Diagnostics plus the v3 equipment-relative <c>{{equip}}/&lt;RefName&gt;</c> resolution check.
+    /// Runs the synchronous Roslyn/policy <see cref="Diagnose"/> then, when an equipment context + catalog
+    /// are present, appends a marker for each <c>{{equip}}/&lt;RefName&gt;</c> whose <c>&lt;RefName&gt;</c> is
+    /// not one of the equipment's reference effective names — flagging exactly what the deploy gate
+    /// (<c>DraftValidator.ValidateEquipReferenceResolution</c>) rejects, so the editor accepts ⇔ publish
+    /// accepts. Inert (base markers only) on the shared ScriptEdit page where <c>EquipmentId</c> is null.</summary>
+    /// <param name="req">The diagnose request (its <c>EquipmentId</c> carries the owning-equipment context).</param>
+    /// <returns>The base diagnostics plus any unresolved-reference markers.</returns>
+    public async Task<DiagnoseResponse> DiagnoseAsync(DiagnoseRequest req)
+    {
+        var baseResp = Diagnose(req);
+        if (_catalog is null || string.IsNullOrEmpty(req.EquipmentId) || string.IsNullOrEmpty(req.Code))
+            return baseResp;
+        try
+        {
+            var code = Normalize(req.Code);
+            if (!code.Contains(EquipmentScriptPaths.EquipTokenPrefix, StringComparison.Ordinal))
+                return baseResp;
+
+            var names = await _catalog.GetEquipmentReferenceNamesAsync(req.EquipmentId, null, CancellationToken.None);
+            var resolvable = new HashSet<string>(names, StringComparer.Ordinal);
+            var markers = new List<DiagnosticMarker>(baseResp.Markers);
+
+            foreach (System.Text.RegularExpressions.Match m in EquipPathLiteralRegex.Matches(code))
+            {
+                var content = m.Groups[2].Value;
+                if (!content.StartsWith(EquipmentScriptPaths.EquipTokenPrefix, StringComparison.Ordinal)) continue;
+                var refName = content.Substring(EquipmentScriptPaths.EquipTokenPrefix.Length);
+                if (refName.Length == 0 || resolvable.Contains(refName)) continue;
+                // Mark the whole literal content span (the {{equip}}/<RefName> path).
+                var span = new Microsoft.CodeAnalysis.Text.TextSpan(m.Groups[2].Index, content.Length);
+                markers.Add(ToUserMarker(code, span,
+                    $"'{EquipmentScriptPaths.EquipTokenPrefix}{refName}' does not resolve — this equipment has no " +
+                    $"reference named '{refName}'. Add a matching reference or correct the path.",
+                    "OTSCRIPT_EQUIPREF"));
+            }
+            return new DiagnoseResponse(markers.Distinct().ToList());
+        }
+        catch (Exception ex)
+        {
+            _logger?.LogWarning(ex, "Script equip-ref diagnostics failed; returning base markers.");
+            return baseResp;
+        }
+    }
+
    private static int Sev(DiagnosticSeverity s) => s switch
    {
        DiagnosticSeverity.Error => 8,
@@ -173,13 +225,17 @@ public sealed class ScriptAnalysisService

            if (_catalog != null && TryGetTagPathLiteral(token, out var pathPrefix, out _))
            {
-                const string equipDot = EquipmentScriptPaths.EquipToken + "."; // "{{equip}}."
-                if (pathPrefix.StartsWith(equipDot, StringComparison.Ordinal))
+                // v3: {{equip}}/<RefName> completes the owning equipment's UnsTagReference effective names
+                // (needs the equipment context — inert on the shared ScriptEdit page where EquipmentId is null).
+                const string equipPrefix = EquipmentScriptPaths.EquipTokenPrefix; // "{{equip}}/"
+                if (pathPrefix.StartsWith(equipPrefix, StringComparison.Ordinal))
                {
-                    var leaves = await _catalog.GetEquipmentRelativeLeavesAsync(
-                        pathPrefix.Substring(equipDot.Length), CancellationToken.None);
-                    return new CompletionsResponse(leaves
-                        .Select(n => new CompletionItem(equipDot + n, equipDot + n, "tag path", "Field"))
+                    if (string.IsNullOrEmpty(req.EquipmentId))
+                        return new CompletionsResponse(Array.Empty<CompletionItem>());
+                    var names = await _catalog.GetEquipmentReferenceNamesAsync(
+                        req.EquipmentId, pathPrefix.Substring(equipPrefix.Length), CancellationToken.None);
+                    return new CompletionsResponse(names
+                        .Select(n => new CompletionItem(equipPrefix + n, equipPrefix + n, "tag path", "Field"))
                        .ToList());
                }

@@ -281,7 +337,8 @@ public sealed class ScriptAnalysisService
                {
                    return new HoverResponse(
                        $"**Equipment-relative path** `{Code(tagPath)}`\n\n" +
-                        "The {{equip}} token is replaced with the owning equipment's tag base when the VirtualTag is deployed.");
+                        "`{{equip}}/<RefName>` resolves through the owning equipment's tag reference " +
+                        "(by effective name) to the backing raw tag's path when the VirtualTag is deployed.");
                }

                var info = await _catalog.GetTagInfoAsync(tagPath, CancellationToken.None);
@@ -0,0 +1,106 @@
+using Microsoft.EntityFrameworkCore;
+using ZB.MOM.WW.OtOpcUa.Configuration;
+
+namespace ZB.MOM.WW.OtOpcUa.AdminUI.Uns;
+
+/// <summary>
+///     Default <see cref="IEffectiveNameGuard"/>. Loads the owning equipment's current effective-name
+///     set — references (<c>DisplayNameOverride</c> else the backing raw tag's <c>Name</c>),
+///     VirtualTags (<c>Name</c>), and ScriptedAlarms (<c>Name</c>) — and reports the first collision
+///     with a proposed name. Comparison is <see cref="StringComparer.Ordinal"/> to match the
+///     <c>{EquipmentId}/{EffectiveName}</c> NodeId semantics and the deploy-time
+///     <c>DraftValidator</c> <c>UnsEffectiveNameCollision</c> rule.
+/// </summary>
+/// <remarks>
+///     Each call creates and disposes its own pooled context — the same per-call pattern
+///     <see cref="UnsTreeService"/> uses — so the guard is safe to register <c>Scoped</c>.
+/// </remarks>
+public sealed class EffectiveNameGuard(IDbContextFactory<OtOpcUaConfigDbContext> dbFactory) : IEffectiveNameGuard
+{
+    /// <inheritdoc />
+    public async Task<string?> CheckAsync(
+        string equipmentId,
+        string proposedEffectiveName,
+        EffectiveNameSourceKind kind,
+        string? excludeSourceId,
+        CancellationToken ct = default)
+    {
+        await using var db = await dbFactory.CreateDbContextAsync(ct);
+
+        // References for this equipment. The effective name is the display-name override else the
+        // backing raw tag's current Name, so the two sets (references + tags) are loaded and joined
+        // in memory — the per-equipment set is small and this mirrors the deploy rule exactly
+        // (a reference whose backing tag is missing contributes no effective name, so it is skipped).
+        var references = await db.UnsTagReferences
+            .AsNoTracking()
+            .Where(r => r.EquipmentId == equipmentId)
+            .Select(r => new { r.UnsTagReferenceId, r.TagId, r.DisplayNameOverride })
+            .ToListAsync(ct);
+
+        var tagIds = references.Select(r => r.TagId).Distinct(StringComparer.Ordinal).ToList();
+        var tagNameById = (await db.Tags
+                .AsNoTracking()
+                .Where(t => tagIds.Contains(t.TagId))
+                .Select(t => new { t.TagId, t.Name })
+                .ToListAsync(ct))
+            .GroupBy(t => t.TagId, StringComparer.Ordinal)
+            .ToDictionary(g => g.Key, g => g.First().Name, StringComparer.Ordinal);
+
+        foreach (var r in references)
+        {
+            if (IsSelf(EffectiveNameSourceKind.Reference, r.UnsTagReferenceId, kind, excludeSourceId))
+                continue;
+            var effective = r.DisplayNameOverride
+                ?? (tagNameById.TryGetValue(r.TagId, out var n) ? n : null);
+            if (Collides(effective, proposedEffectiveName))
+                return Message(proposedEffectiveName, "reference", r.UnsTagReferenceId, equipmentId);
+        }
+
+        var virtualTags = await db.VirtualTags
+            .AsNoTracking()
+            .Where(v => v.EquipmentId == equipmentId)
+            .Select(v => new { v.VirtualTagId, v.Name })
+            .ToListAsync(ct);
+
+        foreach (var v in virtualTags)
+        {
+            if (IsSelf(EffectiveNameSourceKind.VirtualTag, v.VirtualTagId, kind, excludeSourceId))
+                continue;
+            if (Collides(v.Name, proposedEffectiveName))
+                return Message(proposedEffectiveName, "VirtualTag", v.VirtualTagId, equipmentId);
+        }
+
+        var scriptedAlarms = await db.ScriptedAlarms
+            .AsNoTracking()
+            .Where(a => a.EquipmentId == equipmentId)
+            .Select(a => new { a.ScriptedAlarmId, a.Name })
+            .ToListAsync(ct);
+
+        foreach (var a in scriptedAlarms)
+        {
+            if (IsSelf(EffectiveNameSourceKind.ScriptedAlarm, a.ScriptedAlarmId, kind, excludeSourceId))
+                continue;
+            if (Collides(a.Name, proposedEffectiveName))
+                return Message(proposedEffectiveName, "ScriptedAlarm", a.ScriptedAlarmId, equipmentId);
+        }
+
+        return null;
+    }
+
+    /// <summary>True when a row is the self-row being edited — same kind AND same logical id — so it
+    /// is excluded from the collision set (a rename / override-change of a row cannot collide with itself).</summary>
+    private static bool IsSelf(
+        EffectiveNameSourceKind rowKind,
+        string rowId,
+        EffectiveNameSourceKind editedKind,
+        string? excludeSourceId) =>
+        excludeSourceId is not null
+        && rowKind == editedKind
+        && string.Equals(rowId, excludeSourceId, StringComparison.Ordinal);
+
+    private static bool Collides(string? existing, string proposed) =>
+        existing is not null && string.Equals(existing, proposed, StringComparison.Ordinal);
+
+    private static string Message(string name, string sourceLabel, string sourceId, string equipmentId) =>
+        $"effective name '{name}' already used by {sourceLabel} '{sourceId}' in equipment '{equipmentId}'";
+}
@@ -9,3 +9,28 @@ public sealed record EquipmentTagRow(

 /// <summary>A virtual-tag row for the equipment page's Virtual Tags tab table.</summary>
 public sealed record EquipmentVirtualTagRow(string VirtualTagId, string Name, string DataType, string ScriptId, bool Enabled);
+
+/// <summary>
+/// A UNS tag-reference row for the equipment page's Tags tab table (v3 reference-only equipment). Each
+/// row projects a <see cref="Configuration.Entities.UnsTagReference"/> together with the backing raw
+/// tag's inherited (read-only) datatype/access and computed RawPath. The effective name is the
+/// <c>DisplayNameOverride</c> when set, else the backing raw tag's <c>Name</c>. <c>RowVersion</c> is the
+/// reference row's concurrency token, echoed on the override-set / remove mutations.
+/// </summary>
+/// <param name="UnsTagReferenceId">The reference's stable logical id (the mutation key).</param>
+/// <param name="EffectiveName">Override else the raw tag's Name — the UNS leaf name.</param>
+/// <param name="RawPath">The backing raw tag's computed RawPath (folder/driver/device/group/tag).</param>
+/// <param name="DataType">Inherited OPC UA built-in type name from the raw tag (read-only).</param>
+/// <param name="AccessLevel">Inherited access level from the raw tag (read-only).</param>
+/// <param name="DisplayNameOverride">The optional display-name override; <c>null</c> = use the raw name.</param>
+/// <param name="SortOrder">Sibling display ordering within the equipment's Tags list.</param>
+/// <param name="RowVersion">The reference row's optimistic-concurrency token.</param>
+public sealed record EquipmentReferenceRow(
+    string UnsTagReferenceId,
+    string EffectiveName,
+    string RawPath,
+    string DataType,
+    TagAccessLevel AccessLevel,
+    string? DisplayNameOverride,
+    int SortOrder,
+    byte[] RowVersion);
@@ -11,7 +11,6 @@ namespace ZB.MOM.WW.OtOpcUa.AdminUI.Uns;
 /// <param name="Name">UNS level-5 segment; matches <c>^[a-z0-9-]{1,32}$</c>.</param>
 /// <param name="MachineCode">Operator colloquial id; unique fleet-wide.</param>
 /// <param name="UnsLineId">Logical FK to the owning <see cref="Configuration.Entities.UnsLine"/>.</param>
-/// <param name="DriverInstanceId">Optional driver binding; whitespace/empty means driver-less.</param>
 /// <param name="ZTag">Optional ERP equipment id.</param>
 /// <param name="SAPID">Optional SAP PM equipment id.</param>
 /// <param name="Manufacturer">Optional OPC 40010 manufacturer name.</param>
@@ -28,7 +27,6 @@ public sealed record EquipmentInput(
    string Name,
    string MachineCode,
    string UnsLineId,
-    string? DriverInstanceId,
    string? ZTag,
    string? SAPID,
    string? Manufacturer,
@@ -0,0 +1,61 @@
+namespace ZB.MOM.WW.OtOpcUa.AdminUI.Uns;
+
+/// <summary>
+///     Which authoring surface a proposed effective name comes from. Used to word the collision
+///     error and to exclude the correct same-kind self-row on an edit (rename / override change).
+/// </summary>
+public enum EffectiveNameSourceKind
+{
+    /// <summary>A <see cref="Configuration.Entities.UnsTagReference"/> (effective name =
+    /// <c>DisplayNameOverride</c> else the backing raw tag's <c>Name</c>).</summary>
+    Reference,
+
+    /// <summary>An equipment-bound <see cref="Configuration.Entities.VirtualTag"/> (effective name = <c>Name</c>).</summary>
+    VirtualTag,
+
+    /// <summary>An equipment-bound <see cref="Configuration.Entities.ScriptedAlarm"/> (effective name = <c>Name</c>).</summary>
+    ScriptedAlarm,
+}
+
+/// <summary>
+///     v3 Batch 3 authoring-time guard for the UNS effective-name uniqueness rule. Within an
+///     equipment the EFFECTIVE leaf name must be unique across its <c>UnsTagReferences</c>
+///     (<c>DisplayNameOverride</c> else the backing raw tag's <c>Name</c>), its <c>VirtualTags</c>
+///     (<c>Name</c>), and its <c>ScriptedAlarms</c> (<c>Name</c>) — the three share the equipment's
+///     UNS NodeId space (<c>{EquipmentId}/{EffectiveName}</c>). This is the authoring mirror of the
+///     deploy-time <c>DraftValidator</c> <c>UnsEffectiveNameCollision</c> rule; comparison is
+///     <see cref="StringComparer.Ordinal"/> to match NodeId semantics and the validator.
+/// </summary>
+/// <remarks>
+///     Injectable (registered <c>Scoped</c>, its own pooled context per call — the same pattern
+///     <c>UnsTreeService</c> uses). Consumed by <c>UnsTreeService</c>'s reference / virtual-tag /
+///     scripted-alarm mutations, which call <see cref="CheckAsync"/> before persisting and surface a
+///     non-null result as the mutation's readable failure. The deploy gate remains the backstop for
+///     rename-induced collisions the authoring check never saw.
+/// </remarks>
+public interface IEffectiveNameGuard
+{
+    /// <summary>
+    ///     Tests whether <paramref name="proposedEffectiveName"/> would collide with an existing
+    ///     effective name within <paramref name="equipmentId"/>.
+    /// </summary>
+    /// <param name="equipmentId">The owning equipment's logical id.</param>
+    /// <param name="proposedEffectiveName">The effective name to be authored (override else raw name for a reference; Name for a VT/alarm).</param>
+    /// <param name="kind">Which surface the proposed name is for (words the error; identifies the self-row kind to exclude).</param>
+    /// <param name="excludeSourceId">
+    ///     On an edit, the logical id of the row being changed (its <c>UnsTagReferenceId</c> /
+    ///     <c>VirtualTagId</c> / <c>ScriptedAlarmId</c>) so it is excluded from the collision set;
+    ///     <see langword="null"/> on a create.
+    /// </param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>
+    ///     <see langword="null"/> when the name is free; otherwise a readable error naming the
+    ///     colliding existing source and the equipment.
+    /// </returns>
+    Task<string?> CheckAsync(
+        string equipmentId,
+        string proposedEffectiveName,
+        EffectiveNameSourceKind kind,
+        string? excludeSourceId,
+        CancellationToken ct = default);
+}
@@ -139,6 +139,82 @@ public interface IUnsTreeService
    /// <returns>The equipment's virtual-tag rows ordered by Name; empty if it has none.</returns>
    Task<IReadOnlyList<EquipmentVirtualTagRow>> LoadVirtualTagsForEquipmentAsync(string equipmentId, CancellationToken ct = default);

+    // ---------------------------------------------------------------------------------------------
+    // v3 UNS reference-only equipment: the Tags tab lists UnsTagReference rows pointing at raw tags.
+    // ---------------------------------------------------------------------------------------------
+
+    /// <summary>
+    /// Loads the <see cref="Configuration.Entities.UnsTagReference"/> rows for a single equipment as flat
+    /// projections for the equipment page's Tags tab, ordered by <c>SortOrder</c> then effective name.
+    /// Each row carries the effective name (override else the backing raw tag's <c>Name</c>), the backing
+    /// tag's computed RawPath, its inherited (read-only) datatype/access, the optional display-name
+    /// override, and the reference's concurrency token. Reads untracked. Returns an empty list when the
+    /// equipment has no references.
+    /// </summary>
+    /// <param name="equipmentId">The equipment whose references to load.</param>
+    /// <param name="ct">A token to cancel the load.</param>
+    /// <returns>The equipment's reference rows; empty if it has none.</returns>
+    Task<IReadOnlyList<EquipmentReferenceRow>> LoadReferencesForEquipmentAsync(string equipmentId, CancellationToken ct = default);
+
+    /// <summary>
+    /// Adds one <see cref="Configuration.Entities.UnsTagReference"/> per supplied raw <c>TagId</c> to an
+    /// equipment. Every backing tag MUST live in the same cluster as the equipment (cross-cluster
+    /// references are rejected). Each new reference's effective name (the raw tag's <c>Name</c> — no
+    /// override on add) must be unique within the equipment across references, VirtualTags, and
+    /// ScriptedAlarms (enforced via <see cref="IEffectiveNameGuard"/>), and a tag already referenced by
+    /// the equipment is rejected. The batch is all-or-nothing.
+    /// </summary>
+    /// <param name="equipmentId">The referencing equipment.</param>
+    /// <param name="tagIds">The raw tag ids to reference.</param>
+    /// <param name="ct">A token to cancel the operation.</param>
+    /// <returns>Success, or the first guard/cluster/duplicate failure (nothing is added).</returns>
+    Task<UnsMutationResult> AddReferencesAsync(string equipmentId, IReadOnlyList<string> tagIds, CancellationToken ct = default);
+
+    /// <summary>
+    /// Removes a UNS tag reference. A missing row is treated as success (already gone). Uses last-write-wins
+    /// optimistic concurrency on <see cref="Configuration.Entities.UnsTagReference.RowVersion"/>.
+    /// </summary>
+    /// <param name="unsTagReferenceId">The reference to remove.</param>
+    /// <param name="rowVersion">The concurrency token the caller last read.</param>
+    /// <param name="ct">A token to cancel the operation.</param>
+    /// <returns>Success, a concurrency failure, or a delete-failed failure.</returns>
+    Task<UnsMutationResult> RemoveReferenceAsync(string unsTagReferenceId, byte[] rowVersion, CancellationToken ct = default);
+
+    /// <summary>
+    /// Sets (or clears) a reference's <c>DisplayNameOverride</c>. A whitespace-only override collapses to
+    /// <c>null</c> (use the raw name). The resulting effective name (override else the backing raw tag's
+    /// <c>Name</c>) must be unique within the equipment across references, VirtualTags, and ScriptedAlarms
+    /// (enforced via <see cref="IEffectiveNameGuard"/>, excluding this reference). Uses last-write-wins
+    /// optimistic concurrency.
+    /// </summary>
+    /// <param name="unsTagReferenceId">The reference to update.</param>
+    /// <param name="displayNameOverride">The new override, or <c>null</c>/blank to clear it.</param>
+    /// <param name="rowVersion">The concurrency token the caller last read.</param>
+    /// <param name="ct">A token to cancel the operation.</param>
+    /// <returns>Success, a missing-row failure, a name-collision failure, or a concurrency failure.</returns>
+    Task<UnsMutationResult> SetReferenceOverrideAsync(string unsTagReferenceId, string? displayNameOverride, byte[] rowVersion, CancellationToken ct = default);
+
+    /// <summary>
+    /// Builds the single cluster-rooted <see cref="RawNode"/> that seeds the "+ Add reference" raw-tag
+    /// picker for an equipment, structurally scoped to the equipment's own cluster (raw tags in any other
+    /// cluster are unreachable through this root — the scope is enforced by the query, not merely hidden).
+    /// The picker's <c>RawTree</c> lazily expands it via <see cref="IRawTreeService.LoadChildrenAsync"/>.
+    /// Returns <c>null</c> when the equipment cannot be resolved to a cluster.
+    /// </summary>
+    /// <param name="equipmentId">The equipment whose cluster scopes the picker.</param>
+    /// <param name="ct">A token to cancel the load.</param>
+    /// <returns>The cluster root node, or <c>null</c> when the equipment/cluster can't be resolved.</returns>
+    Task<RawNode?> LoadReferencePickerRootAsync(string equipmentId, CancellationToken ct = default);
+
+    /// <summary>
+    /// Enumerates every raw <c>TagId</c> beneath a Device or TagGroup picker node (the whole subtree), for
+    /// the picker's "select all tags below" affordance. Returns an empty list for non-container node kinds.
+    /// </summary>
+    /// <param name="node">The picker node (Device or TagGroup) to enumerate tags under.</param>
+    /// <param name="ct">A token to cancel the query.</param>
+    /// <returns>The tag ids in the node's subtree; empty for unsupported kinds.</returns>
+    Task<IReadOnlyList<string>> LoadDescendantTagIdsAsync(RawNode node, CancellationToken ct = default);
+
    /// <summary>
    /// Loads a single UNS area projected for editing, or <c>null</c> if it no longer exists.
    /// Reads untracked and captures the current concurrency token for last-write-wins saves.
@@ -284,24 +360,22 @@ public interface IUnsTreeService
    /// <summary>
    /// Creates a new equipment under a UNS line. The <c>EquipmentId</c> is system-generated
    /// (<c>EQ-</c> + the first 12 hex chars of a fresh <c>EquipmentUuid</c>).
-    /// Fails if the line is unset, if the MachineCode is already used fleet-wide, or if the
-    /// driver-cluster guard trips. Whitespace-only DriverInstanceId/ZTag/SAPID
-    /// collapse to <c>null</c>.
+    /// Fails if the line is unset or if the MachineCode is already used fleet-wide. Whitespace-only
+    /// ZTag/SAPID collapse to <c>null</c>. (v3: equipment no longer binds a driver — the reference-only
+    /// Tags tab points at raw tags instead — so no driver-cluster guard applies.)
    /// </summary>
    /// <param name="input">The operator-editable equipment fields.</param>
    /// <param name="ct">A token to cancel the operation.</param>
-    /// <returns>Success, a missing-line failure, a duplicate-MachineCode failure, or a cluster-guard failure.</returns>
+    /// <returns>Success, a missing-line failure, or a duplicate-MachineCode failure.</returns>
    Task<UnsMutationResult> CreateEquipmentAsync(EquipmentInput input, CancellationToken ct = default);

    /// <summary>
    /// Bulk-imports equipment from a parsed set of <see cref="EquipmentInput"/> rows in a single
    /// context, applying the same rules as the single-add path: a row whose <c>UnsLineId</c> does not
-    /// exist is an error; a row whose <c>DriverInstanceId</c> is set but does not resolve is an error;
-    /// a driver-bound row whose driver is in a different cluster than its line fails the cluster
-    /// guard; and a row whose <c>MachineCode</c> already exists in the DB <em>or</em> earlier in the
-    /// same batch is silently skipped (additive-only — never an update). Inserted rows get a
+    /// exist is an error; and a row whose <c>MachineCode</c> already exists in the DB <em>or</em> earlier
+    /// in the same batch is silently skipped (additive-only — never an update). Inserted rows get a
    /// system-generated <c>EQ-</c> id and a fresh <c>EquipmentUuid</c>. All inserts are saved once at
-    /// the end.
+    /// the end. (v3: equipment no longer binds a driver, so there is no per-row driver-cluster guard.)
    /// </summary>
    /// <param name="rows">The parsed equipment rows to import.</param>
    /// <param name="ct">A token to cancel the operation.</param>
@@ -309,16 +383,16 @@ public interface IUnsTreeService
    Task<EquipmentImportResult> ImportEquipmentAsync(IReadOnlyList<EquipmentInput> rows, CancellationToken ct = default);

    /// <summary>
-    /// Updates an equipment's mutable fields (driver binding, line, name, MachineCode, external
-    /// ids, and the OPC 40010 identification fields). The driver-cluster guard blocks
-    /// binding to a driver in a different cluster than the equipment's line. Uses last-write-wins
-    /// optimistic concurrency on <see cref="Configuration.Entities.Equipment.RowVersion"/>.
+    /// Updates an equipment's mutable fields (line, name, MachineCode, external ids, and the OPC 40010
+    /// identification fields). Fails on a MachineCode already used by another row. Uses last-write-wins
+    /// optimistic concurrency on <see cref="Configuration.Entities.Equipment.RowVersion"/>. (v3: equipment
+    /// no longer binds a driver, so there is no driver-cluster guard.)
    /// </summary>
    /// <param name="equipmentId">The equipment to update.</param>
    /// <param name="input">The new operator-editable equipment fields.</param>
    /// <param name="rowVersion">The concurrency token the caller last read.</param>
    /// <param name="ct">A token to cancel the operation.</param>
-    /// <returns>Success, a missing-row failure, a cluster-guard failure, or a concurrency failure.</returns>
+    /// <returns>Success, a missing-row failure, a duplicate-MachineCode failure, or a concurrency failure.</returns>
    Task<UnsMutationResult> UpdateEquipmentAsync(string equipmentId, EquipmentInput input, byte[] rowVersion, CancellationToken ct = default);

    /// <summary>
@@ -1282,24 +1282,41 @@ public sealed class RawTreeService(IDbContextFactory<OtOpcUaConfigDbContext> dbF
    }

    /// <summary>
-    /// Builds the non-blocking rename warnings answerable from this batch's schema: historized tags and
-    /// equipment-referenced tags beneath the renamed node (whose RawPath — and thus historian tagname /
-    /// UNS projection path — changes with the rename). Batch 3 appends the script-substring scan here.
+    /// A raw tag affected by a rename, carrying the fields needed to (a) read its platform intents and
+    /// (b) recompute its OLD RawPath (still the in-DB state at warning time — the rename is not yet saved).
+    /// </summary>
+    private readonly record struct AffectedTag(
+        string TagId, string TagConfig, string DeviceId, string? TagGroupId, string Name);
+
+    /// <summary>
+    /// Builds the non-blocking rename warnings answerable from this batch's schema for the tags beneath the
+    /// renamed node (whose RawPath — and thus historian tagname / UNS projection path / script literal —
+    /// changes with the rename): (a) historized tags WITHOUT a <c>historianTagname</c> override (their
+    /// history forks, since the default tagname is the moving RawPath; pinned tags are unaffected),
+    /// (b) equipment-referenced tags, and (c) tags whose OLD RawPath appears as a literal substring in any
+    /// <see cref="Script"/> body (tolerates false positives by design — no AST).
    /// </summary>
    private static async Task<IReadOnlyList<string>> BuildRenameWarningsAsync(
-        OtOpcUaConfigDbContext db, IReadOnlyList<(string TagId, string TagConfig)> tags, CancellationToken ct)
+        OtOpcUaConfigDbContext db, IReadOnlyList<AffectedTag> tags, CancellationToken ct)
    {
        var warnings = new List<string>();
        if (tags.Count == 0) return warnings;

-        var historized = tags.Count(t => TagConfigIntent.Parse(t.TagConfig).IsHistorized);
-        if (historized > 0)
+        // (a) Historized WITHOUT a historianTagname override: the default tagname is the RawPath, which is
+        // moving, so history forks on the next deploy. A tag WITH the override is pinned and does not warn.
+        var forking = tags.Count(t =>
        {
-            warnings.Add(historized == 1
-                ? "1 historized tag beneath this node will change its RawPath (historian tagname). Update the historian if it keys on the old path."
-                : $"{historized} historized tags beneath this node will change their RawPath (historian tagname). Update the historian if it keys on the old paths.");
+            var intent = TagConfigIntent.Parse(t.TagConfig);
+            return intent.IsHistorized && intent.HistorianTagname is null;
+        });
+        if (forking > 0)
+        {
+            warnings.Add(forking == 1
+                ? "1 historized tag beneath this node has no historianTagname override; its history forks to a new tagname when its RawPath changes on the next deploy. Set a historianTagname to pin it."
+                : $"{forking} historized tags beneath this node have no historianTagname override; their history forks to new tagnames when their RawPaths change on the next deploy. Set a historianTagname to pin them.");
        }

+        // (b) UNS-referenced: name the referencing equipment.
        var tagIds = tags.Select(t => t.TagId).ToList();
        var referencingEquipmentIds = await db.UnsTagReferences.AsNoTracking()
            .Where(r => tagIds.Contains(r.TagId))
@@ -1313,12 +1330,94 @@ public sealed class RawTreeService(IDbContextFactory<OtOpcUaConfigDbContext> dbF
            warnings.Add($"Tags beneath this node are referenced by equipment {display}; the UNS projection path will change with the rename.");
        }

-        // Batch 3 extension point: scan scripts for substrings of the affected tags' RawPaths and append
-        // a "N script(s) reference tags beneath this node" warning to this same list.
+        // (c) Script literals: substring-scan every Script body for the affected tags' OLD RawPaths.
+        var scriptWarning = await BuildScriptReferenceWarningAsync(db, tags, ct);
+        if (scriptWarning is not null) warnings.Add(scriptWarning);

        return warnings;
    }

+    /// <summary>
+    /// Scans every <see cref="Script"/> body for the OLD RawPath of any affected tag as a plain ordinal
+    /// substring (no AST — false positives tolerated by design; <c>{{equip}}</c>-relative refs are NOT
+    /// scanned, they resolve through references and the deploy gate catches breakage). Returns a warning
+    /// naming the matched scripts, or <see langword="null"/> when none match.
+    /// </summary>
+    private static async Task<string?> BuildScriptReferenceWarningAsync(
+        OtOpcUaConfigDbContext db, IReadOnlyList<AffectedTag> tags, CancellationToken ct)
+    {
+        var oldPaths = await ComputeOldRawPathsAsync(db, tags, ct);
+        if (oldPaths.Count == 0) return null;
+
+        var scripts = await db.Scripts.AsNoTracking()
+            .Select(s => new { s.ScriptId, s.Name, s.SourceCode })
+            .ToListAsync(ct);
+
+        var matched = scripts
+            .Where(s => oldPaths.Any(p => s.SourceCode.Contains(p, StringComparison.Ordinal)))
+            .OrderBy(s => s.Name, StringComparer.Ordinal)
+            .Select(s => s.Name)
+            .ToList();
+        if (matched.Count == 0) return null;
+
+        var names = string.Join(", ", matched.Select(n => $"'{n}'"));
+        return matched.Count == 1
+            ? $"1 script ({names}) references a tag beneath this node by its raw path; the reference will break unless the script is updated."
+            : $"{matched.Count} scripts ({names}) reference tags beneath this node by their raw paths; the references will break unless the scripts are updated.";
+    }
+
+    /// <summary>
+    /// Recomputes the OLD RawPath of each affected tag from the current (pre-save) in-DB raw topology,
+    /// dropping any tag whose ancestry chain is broken (a null RawPath). Loads only the topology the affected
+    /// tags need: their devices + drivers, the drivers' clusters' folders, and the devices' tag groups.
+    /// </summary>
+    private static async Task<IReadOnlyList<string>> ComputeOldRawPathsAsync(
+        OtOpcUaConfigDbContext db, IReadOnlyList<AffectedTag> tags, CancellationToken ct)
+    {
+        var deviceIds = tags.Select(t => t.DeviceId).Distinct(StringComparer.Ordinal).ToList();
+
+        var deviceRows = await db.Devices.AsNoTracking()
+            .Where(d => deviceIds.Contains(d.DeviceId))
+            .Select(d => new { d.DeviceId, d.DriverInstanceId, d.Name })
+            .ToListAsync(ct);
+
+        var driverIds = deviceRows.Select(d => d.DriverInstanceId).Distinct(StringComparer.Ordinal).ToList();
+        var driverRows = await db.DriverInstances.AsNoTracking()
+            .Where(d => driverIds.Contains(d.DriverInstanceId))
+            .Select(d => new { d.DriverInstanceId, d.RawFolderId, d.Name, d.ClusterId })
+            .ToListAsync(ct);
+
+        var clusterIds = driverRows.Select(d => d.ClusterId).Distinct(StringComparer.Ordinal).ToList();
+        var folderRows = await db.RawFolders.AsNoTracking()
+            .Where(f => clusterIds.Contains(f.ClusterId))
+            .Select(f => new { f.RawFolderId, f.ParentRawFolderId, f.Name })
+            .ToListAsync(ct);
+
+        var groupRows = await db.TagGroups.AsNoTracking()
+            .Where(g => deviceIds.Contains(g.DeviceId))
+            .Select(g => new { g.TagGroupId, g.ParentTagGroupId, g.Name })
+            .ToListAsync(ct);
+
+        var folders = folderRows.ToDictionary(
+            f => f.RawFolderId, f => ((string?)f.ParentRawFolderId, f.Name), StringComparer.Ordinal);
+        var drivers = driverRows.ToDictionary(
+            d => d.DriverInstanceId, d => ((string?)d.RawFolderId, d.Name), StringComparer.Ordinal);
+        var devices = deviceRows.ToDictionary(
+            d => d.DeviceId, d => (d.DriverInstanceId, d.Name), StringComparer.Ordinal);
+        var groups = groupRows.ToDictionary(
+            g => g.TagGroupId, g => ((string?)g.ParentTagGroupId, g.Name), StringComparer.Ordinal);
+
+        var resolver = new RawPathResolver(folders, drivers, devices, groups);
+
+        var paths = new List<string>(tags.Count);
+        foreach (var t in tags)
+        {
+            var path = resolver.TryBuildTagPath(t.DeviceId, t.TagGroupId, t.Name);
+            if (path is not null) paths.Add(path);
+        }
+        return paths;
+    }
+
    /// <summary>Renders a friendly "<c>Name (Id)</c>, …" list for the referencing equipment ids.</summary>
    private static async Task<string> DescribeEquipmentAsync(
        OtOpcUaConfigDbContext db, IReadOnlyList<string> equipmentIds, CancellationToken ct)
@@ -1336,11 +1435,11 @@ public sealed class RawTreeService(IDbContextFactory<OtOpcUaConfigDbContext> dbF

    // --- Subtree tag collectors (walk the in-DB subtree for rename impact) ---

-    private static async Task<IReadOnlyList<(string TagId, string TagConfig)>> CollectTagsBeneathFolderAsync(
+    private static async Task<IReadOnlyList<AffectedTag>> CollectTagsBeneathFolderAsync(
        OtOpcUaConfigDbContext db, string rawFolderId, CancellationToken ct)
    {
        var folder = await db.RawFolders.AsNoTracking().FirstOrDefaultAsync(f => f.RawFolderId == rawFolderId, ct);
-        if (folder is null) return Array.Empty<(string, string)>();
+        if (folder is null) return Array.Empty<AffectedTag>();

        // All folders in the cluster, walked in-memory to the descendant set (incl. self) via ParentRawFolderId.
        var clusterFolders = await db.RawFolders.AsNoTracking()
@@ -1359,44 +1458,44 @@ public sealed class RawTreeService(IDbContextFactory<OtOpcUaConfigDbContext> dbF
            .Where(d => d.RawFolderId != null && folderIds.Contains(d.RawFolderId))
            .Select(d => d.DriverInstanceId)
            .ToListAsync(ct);
-        if (driverIds.Count == 0) return Array.Empty<(string, string)>();
+        if (driverIds.Count == 0) return Array.Empty<AffectedTag>();

        var deviceIds = await db.Devices.AsNoTracking()
            .Where(dev => driverIds.Contains(dev.DriverInstanceId))
            .Select(dev => dev.DeviceId)
            .ToListAsync(ct);
-        if (deviceIds.Count == 0) return Array.Empty<(string, string)>();
+        if (deviceIds.Count == 0) return Array.Empty<AffectedTag>();

        return await TagsForDevicesAsync(db, deviceIds, ct);
    }

-    private static async Task<IReadOnlyList<(string TagId, string TagConfig)>> CollectTagsBeneathDriverAsync(
+    private static async Task<IReadOnlyList<AffectedTag>> CollectTagsBeneathDriverAsync(
        OtOpcUaConfigDbContext db, string driverInstanceId, CancellationToken ct)
    {
        var deviceIds = await db.Devices.AsNoTracking()
            .Where(dev => dev.DriverInstanceId == driverInstanceId)
            .Select(dev => dev.DeviceId)
            .ToListAsync(ct);
-        if (deviceIds.Count == 0) return Array.Empty<(string, string)>();
+        if (deviceIds.Count == 0) return Array.Empty<AffectedTag>();
        return await TagsForDevicesAsync(db, deviceIds, ct);
    }

-    private static async Task<IReadOnlyList<(string TagId, string TagConfig)>> CollectTagsBeneathDeviceAsync(
+    private static async Task<IReadOnlyList<AffectedTag>> CollectTagsBeneathDeviceAsync(
        OtOpcUaConfigDbContext db, string deviceId, CancellationToken ct)
    {
        return (await db.Tags.AsNoTracking()
                .Where(t => t.DeviceId == deviceId)
-                .Select(t => new { t.TagId, t.TagConfig })
+                .Select(t => new { t.TagId, t.TagConfig, t.DeviceId, t.TagGroupId, t.Name })
                .ToListAsync(ct))
-            .Select(t => (t.TagId, t.TagConfig))
+            .Select(t => new AffectedTag(t.TagId, t.TagConfig, t.DeviceId, t.TagGroupId, t.Name))
            .ToList();
    }

-    private static async Task<IReadOnlyList<(string TagId, string TagConfig)>> CollectTagsBeneathGroupAsync(
+    private static async Task<IReadOnlyList<AffectedTag>> CollectTagsBeneathGroupAsync(
        OtOpcUaConfigDbContext db, string tagGroupId, CancellationToken ct)
    {
        var group = await db.TagGroups.AsNoTracking().FirstOrDefaultAsync(g => g.TagGroupId == tagGroupId, ct);
-        if (group is null) return Array.Empty<(string, string)>();
+        if (group is null) return Array.Empty<AffectedTag>();

        var deviceGroups = await db.TagGroups.AsNoTracking()
            .Where(g => g.DeviceId == group.DeviceId)
@@ -1412,20 +1511,20 @@ public sealed class RawTreeService(IDbContextFactory<OtOpcUaConfigDbContext> dbF

        return (await db.Tags.AsNoTracking()
                .Where(t => t.TagGroupId != null && groupIds.Contains(t.TagGroupId))
-                .Select(t => new { t.TagId, t.TagConfig })
+                .Select(t => new { t.TagId, t.TagConfig, t.DeviceId, t.TagGroupId, t.Name })
                .ToListAsync(ct))
-            .Select(t => (t.TagId, t.TagConfig))
+            .Select(t => new AffectedTag(t.TagId, t.TagConfig, t.DeviceId, t.TagGroupId, t.Name))
            .ToList();
    }

-    private static async Task<IReadOnlyList<(string TagId, string TagConfig)>> TagsForDevicesAsync(
+    private static async Task<IReadOnlyList<AffectedTag>> TagsForDevicesAsync(
        OtOpcUaConfigDbContext db, IReadOnlyList<string> deviceIds, CancellationToken ct)
    {
        return (await db.Tags.AsNoTracking()
                .Where(t => deviceIds.Contains(t.DeviceId))
-                .Select(t => new { t.TagId, t.TagConfig })
+                .Select(t => new { t.TagId, t.TagConfig, t.DeviceId, t.TagGroupId, t.Name })
                .ToListAsync(ct))
-            .Select(t => (t.TagId, t.TagConfig))
+            .Select(t => new AffectedTag(t.TagId, t.TagConfig, t.DeviceId, t.TagGroupId, t.Name))
            .ToList();
    }

@@ -18,8 +18,17 @@ namespace ZB.MOM.WW.OtOpcUa.AdminUI.Uns;
 /// every AdminUI page uses — so the service is safe to register as Scoped and used per
 /// Blazor circuit.
 /// </remarks>
-public sealed class UnsTreeService(IDbContextFactory<OtOpcUaConfigDbContext> dbFactory) : IUnsTreeService
+public sealed class UnsTreeService(
+    IDbContextFactory<OtOpcUaConfigDbContext> dbFactory,
+    IEffectiveNameGuard? guard = null) : IUnsTreeService
 {
+    // The v3 Batch-3 effective-name uniqueness guard (references / VirtualTags / ScriptedAlarms share the
+    // equipment's UNS NodeId space). WP2 registers the real implementation; production DI always injects it.
+    // A null (unregistered) guard falls back to a no-op — collisions are then caught only at the deploy
+    // gate — which also lets unit tests that don't exercise the guard construct the service with just a
+    // db factory. Tests that DO exercise the guard pass a fake.
+    private readonly IEffectiveNameGuard _guard = guard ?? NoOpEffectiveNameGuard.Instance;
+
    /// <inheritdoc />
    public async Task<IReadOnlyList<UnsNode>> LoadStructureAsync(CancellationToken ct = default)
    {
@@ -97,6 +106,371 @@ public sealed class UnsTreeService(IDbContextFactory<OtOpcUaConfigDbContext> dbF
            .ToListAsync(ct);
    }

+    // ---------------------------------------------------------------------------------------------
+    // v3 UNS reference-only equipment (Batch 3): the Tags tab lists UnsTagReference rows.
+    // ---------------------------------------------------------------------------------------------
+
+    /// <inheritdoc />
+    public async Task<IReadOnlyList<EquipmentReferenceRow>> LoadReferencesForEquipmentAsync(
+        string equipmentId, CancellationToken ct = default)
+    {
+        await using var db = await dbFactory.CreateDbContextAsync(ct);
+
+        var refs = await db.UnsTagReferences.AsNoTracking()
+            .Where(r => r.EquipmentId == equipmentId)
+            .OrderBy(r => r.SortOrder).ThenBy(r => r.UnsTagReferenceId)
+            .Select(r => new
+            {
+                r.UnsTagReferenceId,
+                r.TagId,
+                r.DisplayNameOverride,
+                r.SortOrder,
+                r.RowVersion,
+            })
+            .ToListAsync(ct);
+
+        if (refs.Count == 0) return Array.Empty<EquipmentReferenceRow>();
+
+        // Load the backing raw tags (name + inherited datatype/access), then compute each RawPath from the
+        // equipment cluster's raw topology through the shared RawPathResolver (identity authority).
+        var tagIds = refs.Select(r => r.TagId).Distinct().ToList();
+        var tags = (await db.Tags.AsNoTracking()
+                .Where(t => tagIds.Contains(t.TagId))
+                .Select(t => new { t.TagId, t.DeviceId, t.TagGroupId, t.Name, t.DataType, t.AccessLevel })
+                .ToListAsync(ct))
+            .ToDictionary(t => t.TagId, StringComparer.Ordinal);
+
+        var cluster = await ResolveEquipmentClusterAsync(db, equipmentId, ct);
+        var resolver = await BuildClusterRawPathResolverAsync(db, cluster, ct);
+
+        var rows = new List<EquipmentReferenceRow>(refs.Count);
+        foreach (var r in refs)
+        {
+            if (!tags.TryGetValue(r.TagId, out var tag))
+            {
+                // Backing tag missing (should not happen — raw-tag delete is reference-blocked); surface a
+                // clearly-degraded row rather than dropping it so the operator can remove the dangling ref.
+                rows.Add(new EquipmentReferenceRow(
+                    r.UnsTagReferenceId, r.DisplayNameOverride ?? "(missing tag)", "(missing tag)",
+                    "", TagAccessLevel.Read, r.DisplayNameOverride, r.SortOrder, r.RowVersion));
+                continue;
+            }
+
+            var rawPath = resolver?.TryBuildTagPath(tag.DeviceId, tag.TagGroupId, tag.Name) ?? tag.Name;
+            var effectiveName = string.IsNullOrEmpty(r.DisplayNameOverride) ? tag.Name : r.DisplayNameOverride;
+            rows.Add(new EquipmentReferenceRow(
+                r.UnsTagReferenceId, effectiveName, rawPath, tag.DataType, tag.AccessLevel,
+                r.DisplayNameOverride, r.SortOrder, r.RowVersion));
+        }
+
+        return rows;
+    }
+
+    /// <inheritdoc />
+    public async Task<UnsMutationResult> AddReferencesAsync(
+        string equipmentId, IReadOnlyList<string> tagIds, CancellationToken ct = default)
+    {
+        ArgumentNullException.ThrowIfNull(tagIds);
+        var distinctTagIds = tagIds.Where(t => !string.IsNullOrEmpty(t)).Distinct(StringComparer.Ordinal).ToList();
+        if (distinctTagIds.Count == 0) return new UnsMutationResult(false, "Pick at least one raw tag to reference.");
+
+        await using var db = await dbFactory.CreateDbContextAsync(ct);
+
+        if (!await db.Equipment.AnyAsync(e => e.EquipmentId == equipmentId, ct))
+            return new UnsMutationResult(false, $"Equipment '{equipmentId}' not found.");
+
+        var equipmentCluster = await ResolveEquipmentClusterAsync(db, equipmentId, ct);
+        if (equipmentCluster is null)
+            return new UnsMutationResult(false, $"Equipment '{equipmentId}' does not resolve to a cluster.");
+
+        // Load the backing tags + the cluster each lives in (Tag → Device → DriverInstance.ClusterId).
+        var tags = await db.Tags.AsNoTracking()
+            .Where(t => distinctTagIds.Contains(t.TagId))
+            .Join(db.Devices.AsNoTracking(), t => t.DeviceId, dev => dev.DeviceId, (t, dev) => new { t, dev.DriverInstanceId })
+            .Join(db.DriverInstances.AsNoTracking(), x => x.DriverInstanceId, d => d.DriverInstanceId,
+                (x, d) => new { x.t.TagId, x.t.Name, DriverCluster = d.ClusterId })
+            .ToListAsync(ct);
+
+        var tagById = tags.ToDictionary(t => t.TagId, StringComparer.Ordinal);
+
+        // Existing references on the equipment (to reject re-referencing the same tag).
+        var alreadyReferenced = (await db.UnsTagReferences.AsNoTracking()
+                .Where(r => r.EquipmentId == equipmentId)
+                .Select(r => r.TagId)
+                .ToListAsync(ct))
+            .ToHashSet(StringComparer.Ordinal);
+
+        var maxSort = await db.UnsTagReferences.AsNoTracking()
+            .Where(r => r.EquipmentId == equipmentId)
+            .Select(r => (int?)r.SortOrder)
+            .MaxAsync(ct) ?? -1;
+
+        // Track effective names proposed within THIS batch so two raw tags sharing a Name are caught (the
+        // guard sees only persisted rows; a same-batch collision would otherwise slip through).
+        var batchNames = new HashSet<string>(StringComparer.Ordinal);
+        var pending = new List<UnsTagReference>();
+
+        foreach (var tagId in distinctTagIds)
+        {
+            if (!tagById.TryGetValue(tagId, out var tag))
+                return new UnsMutationResult(false, $"Raw tag '{tagId}' not found.");
+
+            if (!string.Equals(tag.DriverCluster, equipmentCluster, StringComparison.Ordinal))
+                return new UnsMutationResult(false,
+                    $"Raw tag '{tag.Name}' is in cluster '{tag.DriverCluster}' but the equipment is in cluster '{equipmentCluster}' — cross-cluster references are not allowed.");
+
+            if (alreadyReferenced.Contains(tagId))
+                return new UnsMutationResult(false, $"Raw tag '{tag.Name}' is already referenced by this equipment.");
+
+            // Effective name at add = the raw tag's Name (no override yet).
+            if (!batchNames.Add(tag.Name))
+                return new UnsMutationResult(false,
+                    $"Two selected raw tags share the effective name '{tag.Name}'; set a display-name override so they stay unique within the equipment.");
+
+            var collision = await _guard.CheckAsync(equipmentId, tag.Name, EffectiveNameSourceKind.Reference, null, ct);
+            if (collision is not null) return new UnsMutationResult(false, collision);
+
+            pending.Add(new UnsTagReference
+            {
+                UnsTagReferenceId = $"UTR-{Guid.NewGuid():N}"[..16],
+                EquipmentId = equipmentId,
+                TagId = tagId,
+                DisplayNameOverride = null,
+                SortOrder = ++maxSort,
+            });
+        }
+
+        db.UnsTagReferences.AddRange(pending);
+        try
+        {
+            await db.SaveChangesAsync(ct);
+            return new UnsMutationResult(true, null);
+        }
+        catch (DbUpdateException)
+        {
+            // The UX_UnsTagReference_Equip_Tag unique index tripped: a concurrent add slipped a
+            // same-(equipment,tag) row past the pre-check. (Effective-name collisions have no DB
+            // uniqueness — those are caught by the authoring guard and the deploy gate, not here.)
+            return new UnsMutationResult(false, "Add failed — a reference at one of these tags was created concurrently. Reload and retry.");
+        }
+    }
+
+    /// <inheritdoc />
+    public async Task<UnsMutationResult> RemoveReferenceAsync(
+        string unsTagReferenceId, byte[] rowVersion, CancellationToken ct = default)
+    {
+        await using var db = await dbFactory.CreateDbContextAsync(ct);
+
+        var entity = await db.UnsTagReferences.FirstOrDefaultAsync(r => r.UnsTagReferenceId == unsTagReferenceId, ct);
+        if (entity is null) return new UnsMutationResult(true, null);
+
+        db.Entry(entity).Property(e => e.RowVersion).OriginalValue = rowVersion;
+        db.UnsTagReferences.Remove(entity);
+
+        try
+        {
+            await db.SaveChangesAsync(ct);
+            return new UnsMutationResult(true, null);
+        }
+        catch (DbUpdateConcurrencyException)
+        {
+            return new UnsMutationResult(false, "Another user changed this reference while you were viewing it.");
+        }
+        catch (Exception ex)
+        {
+            return new UnsMutationResult(false, $"Remove failed: {ex.Message}.");
+        }
+    }
+
+    /// <inheritdoc />
+    public async Task<UnsMutationResult> SetReferenceOverrideAsync(
+        string unsTagReferenceId, string? displayNameOverride, byte[] rowVersion, CancellationToken ct = default)
+    {
+        var normalized = string.IsNullOrWhiteSpace(displayNameOverride) ? null : displayNameOverride.Trim();
+
+        await using var db = await dbFactory.CreateDbContextAsync(ct);
+
+        var entity = await db.UnsTagReferences.FirstOrDefaultAsync(r => r.UnsTagReferenceId == unsTagReferenceId, ct);
+        if (entity is null) return new UnsMutationResult(false, "Row no longer exists.");
+
+        db.Entry(entity).Property(e => e.RowVersion).OriginalValue = rowVersion;
+
+        // Effective name = the override when set, else the backing raw tag's Name.
+        var rawName = await db.Tags.AsNoTracking()
+            .Where(t => t.TagId == entity.TagId)
+            .Select(t => t.Name)
+            .FirstOrDefaultAsync(ct);
+        var effectiveName = normalized ?? rawName ?? string.Empty;
+
+        var collision = await _guard.CheckAsync(
+            entity.EquipmentId, effectiveName, EffectiveNameSourceKind.Reference, entity.UnsTagReferenceId, ct);
+        if (collision is not null) return new UnsMutationResult(false, collision);
+
+        entity.DisplayNameOverride = normalized;
+
+        try
+        {
+            await db.SaveChangesAsync(ct);
+            return new UnsMutationResult(true, null);
+        }
+        catch (DbUpdateConcurrencyException)
+        {
+            return new UnsMutationResult(false, "Another user changed this reference while you were editing.");
+        }
+    }
+
+    /// <inheritdoc />
+    public async Task<RawNode?> LoadReferencePickerRootAsync(string equipmentId, CancellationToken ct = default)
+    {
+        await using var db = await dbFactory.CreateDbContextAsync(ct);
+
+        var clusterId = await ResolveEquipmentClusterAsync(db, equipmentId, ct);
+        if (clusterId is null) return null;
+
+        var cluster = await db.ServerClusters.AsNoTracking()
+            .FirstOrDefaultAsync(c => c.ClusterId == clusterId, ct);
+        if (cluster is null) return null;
+
+        // Root child count = cluster-root folders + cluster-root drivers (the RawTree lazily loads the rest
+        // via IRawTreeService.LoadChildrenAsync, keyed on this node's Cluster kind + EntityId).
+        var rootFolders = await db.RawFolders.AsNoTracking()
+            .CountAsync(f => f.ClusterId == clusterId && f.ParentRawFolderId == null, ct);
+        var rootDrivers = await db.DriverInstances.AsNoTracking()
+            .CountAsync(d => d.ClusterId == clusterId && d.RawFolderId == null, ct);
+
+        return new RawNode
+        {
+            Kind = RawNodeKind.Cluster,
+            Key = $"clu:{clusterId}",
+            DisplayName = cluster.Name,
+            ClusterId = clusterId,
+            EntityId = clusterId,
+            HasLazyChildren = true,
+            ChildCount = rootFolders + rootDrivers,
+        };
+    }
+
+    /// <inheritdoc />
+    public async Task<IReadOnlyList<string>> LoadDescendantTagIdsAsync(RawNode node, CancellationToken ct = default)
+    {
+        ArgumentNullException.ThrowIfNull(node);
+        if (node.EntityId is null) return Array.Empty<string>();
+
+        await using var db = await dbFactory.CreateDbContextAsync(ct);
+
+        switch (node.Kind)
+        {
+            case RawNodeKind.Device:
+                // Every tag under the device (across all its tag groups).
+                return await db.Tags.AsNoTracking()
+                    .Where(t => t.DeviceId == node.EntityId)
+                    .Select(t => t.TagId)
+                    .ToListAsync(ct);
+
+            case RawNodeKind.TagGroup:
+            {
+                // The group + all descendant groups, then every tag in that group set.
+                var group = await db.TagGroups.AsNoTracking()
+                    .FirstOrDefaultAsync(g => g.TagGroupId == node.EntityId, ct);
+                if (group is null) return Array.Empty<string>();
+
+                var deviceGroups = await db.TagGroups.AsNoTracking()
+                    .Where(g => g.DeviceId == group.DeviceId)
+                    .Select(g => new { g.TagGroupId, g.ParentTagGroupId })
+                    .ToListAsync(ct);
+
+                var childrenByParent = deviceGroups
+                    .Where(g => g.ParentTagGroupId is not null)
+                    .GroupBy(g => g.ParentTagGroupId!, StringComparer.Ordinal)
+                    .ToDictionary(g => g.Key, g => g.Select(x => x.TagGroupId).ToList(), StringComparer.Ordinal);
+
+                var groupIds = DescendantGroupsInclusive(node.EntityId, childrenByParent);
+                return await db.Tags.AsNoTracking()
+                    .Where(t => t.TagGroupId != null && groupIds.Contains(t.TagGroupId))
+                    .Select(t => t.TagId)
+                    .ToListAsync(ct);
+            }
+
+            default:
+                // The picker only offers "select all" on Device / TagGroup containers.
+                return Array.Empty<string>();
+        }
+    }
+
+    /// <summary>Returns <paramref name="rootId"/> plus all transitive descendant group ids (iterative walk).</summary>
+    private static HashSet<string> DescendantGroupsInclusive(
+        string rootId, IReadOnlyDictionary<string, List<string>> childrenByParent)
+    {
+        var result = new HashSet<string>(StringComparer.Ordinal);
+        var stack = new Stack<string>();
+        stack.Push(rootId);
+        while (stack.Count > 0)
+        {
+            var id = stack.Pop();
+            if (!result.Add(id)) continue;
+            if (childrenByParent.TryGetValue(id, out var kids))
+            {
+                foreach (var kid in kids) stack.Push(kid);
+            }
+        }
+        return result;
+    }
+
+    /// <summary>
+    /// Builds a <see cref="RawPathResolver"/> over a cluster's raw topology (folders / drivers / devices /
+    /// tag-groups), so a referenced tag's RawPath can be computed the same way the deploy validator does.
+    /// Returns <see langword="null"/> when the cluster is unknown/null (callers then fall back to bare name).
+    /// </summary>
+    private static async Task<RawPathResolver?> BuildClusterRawPathResolverAsync(
+        OtOpcUaConfigDbContext db, string? clusterId, CancellationToken ct)
+    {
+        if (string.IsNullOrEmpty(clusterId)) return null;
+
+        var folders = (await db.RawFolders.AsNoTracking()
+                .Where(f => f.ClusterId == clusterId)
+                .Select(f => new { f.RawFolderId, f.ParentRawFolderId, f.Name })
+                .ToListAsync(ct))
+            .ToDictionary(f => f.RawFolderId, f => ((string?)f.ParentRawFolderId, f.Name), StringComparer.Ordinal);
+
+        var drivers = (await db.DriverInstances.AsNoTracking()
+                .Where(d => d.ClusterId == clusterId)
+                .Select(d => new { d.DriverInstanceId, d.RawFolderId, d.Name })
+                .ToListAsync(ct))
+            .ToDictionary(d => d.DriverInstanceId, d => ((string?)d.RawFolderId, d.Name), StringComparer.Ordinal);
+
+        var driverIds = drivers.Keys.ToList();
+
+        var devices = (await db.Devices.AsNoTracking()
+                .Where(dev => driverIds.Contains(dev.DriverInstanceId))
+                .Select(dev => new { dev.DeviceId, dev.DriverInstanceId, dev.Name })
+                .ToListAsync(ct))
+            .ToDictionary(dev => dev.DeviceId, dev => (dev.DriverInstanceId, dev.Name), StringComparer.Ordinal);
+
+        var deviceIds = devices.Keys.ToList();
+
+        var groups = (await db.TagGroups.AsNoTracking()
+                .Where(g => deviceIds.Contains(g.DeviceId))
+                .Select(g => new { g.TagGroupId, g.ParentTagGroupId, g.Name })
+                .ToListAsync(ct))
+            .ToDictionary(g => g.TagGroupId, g => ((string?)g.ParentTagGroupId, g.Name), StringComparer.Ordinal);
+
+        return new RawPathResolver(folders, drivers, devices, groups);
+    }
+
+    /// <summary>
+    /// A no-op <see cref="IEffectiveNameGuard"/> used only when no guard was injected (unit tests that do
+    /// not exercise the guard; a mis-wired DI). It always reports "free" — the deploy gate remains the
+    /// backstop. Production always injects the real WP2 guard.
+    /// </summary>
+    private sealed class NoOpEffectiveNameGuard : IEffectiveNameGuard
+    {
+        public static readonly NoOpEffectiveNameGuard Instance = new();
+
+        public Task<string?> CheckAsync(
+            string equipmentId, string proposedEffectiveName, EffectiveNameSourceKind kind,
+            string? excludeSourceId, CancellationToken ct = default) => Task.FromResult<string?>(null);
+    }
+
    /// <inheritdoc />
    public async Task<AreaEditDto?> LoadAreaAsync(string unsAreaId, CancellationToken ct = default)
    {
@@ -446,11 +820,8 @@ public sealed class UnsTreeService(IDbContextFactory<OtOpcUaConfigDbContext> dbF
            return new UnsMutationResult(false, $"MachineCode '{input.MachineCode}' already exists in this fleet.");
        }

-        var guard = await CheckDriverClusterGuardAsync(db, input, ct);
-        if (guard is not null)
-        {
-            return guard.Value;
-        }
+        // v3: equipment no longer binds a driver — the reference-only Tags tab points at raw tags — so
+        // the old decision-#122 driver-cluster guard is gone.

        var uuid = Guid.NewGuid();
        var equipmentId = $"EQ-{uuid.ToString("N")[..12]}";
@@ -514,14 +885,7 @@ public sealed class UnsTreeService(IDbContextFactory<OtOpcUaConfigDbContext> dbF
                continue;
            }

-            // Reuse the driver/line cluster guard: it reports an unknown DriverInstanceId and a
-            // driver/line cluster mismatch, and is a no-op for driver-less rows.
-            var guard = await CheckDriverClusterGuardAsync(db, row, ct);
-            if (guard is not null)
-            {
-                errors.Add($"Row '{row.MachineCode}': {guard.Value.Error}");
-                continue;
-            }
+            // v3: equipment no longer binds a driver, so there is no per-row driver-cluster guard.

            var uuid = Guid.NewGuid();
            var equipmentId = $"EQ-{uuid.ToString("N")[..12]}";
@@ -578,11 +942,7 @@ public sealed class UnsTreeService(IDbContextFactory<OtOpcUaConfigDbContext> dbF
            return new UnsMutationResult(false, $"MachineCode '{input.MachineCode}' already exists in this fleet.");
        }

-        var guard = await CheckDriverClusterGuardAsync(db, input, ct);
-        if (guard is not null)
-        {
-            return guard.Value;
-        }
+        // v3: equipment no longer binds a driver — no decision-#122 driver-cluster guard.

        // Equipment↔driver binding retired in v3 — no DriverInstanceId column remains.
        entity.UnsLineId = input.UnsLineId;
@@ -866,29 +1226,82 @@ public sealed class UnsTreeService(IDbContextFactory<OtOpcUaConfigDbContext> dbF
    }

    /// <summary>
-    /// When the bound script uses the reserved <c>{{equip}}</c> token, the owning equipment must have
-    /// a derivable tag base (≥1 driver tag, all sharing one object prefix). Returns a rejection result
-    /// when the token is present but no base can be derived; <c>null</c> otherwise (token absent, or a
-    /// base exists). The script source is fetched from the supplied (in-scope) context.
+    /// v3 (M1): when the bound script uses <c>{{equip}}/&lt;RefName&gt;</c>, every <c>&lt;RefName&gt;</c> must
+    /// resolve to one of the owning equipment's <c>UnsTagReference</c> effective names (its
+    /// <c>DisplayNameOverride</c> else the backing raw tag's <c>Name</c>) — the same set the compose seams
+    /// substitute against and the deploy gate (<c>DraftValidator.ValidateEquipReferenceResolution</c>)
+    /// enforces. Returns a readable rejection naming the missing ref(s) when any is unresolved; <c>null</c>
+    /// otherwise (no slash-token, or all resolve). Replaces the v2 <c>DeriveEquipmentBase(empty)→null</c>
+    /// check, which rejected ALL <c>{{equip}}</c> VirtualTags with a now-impossible "add a driver tag" message.
    /// </summary>
    private static async Task<UnsMutationResult?> ValidateEquipTokenAsync(
        OtOpcUaConfigDbContext db, string equipmentId, string scriptId, CancellationToken ct)
    {
        var src = await db.Scripts.Where(s => s.ScriptId == scriptId)
            .Select(s => s.SourceCode).FirstOrDefaultAsync(ct);
-        if (!EquipmentScriptPaths.ContainsEquipToken(src)) return null;
+        var used = EquipmentScriptPaths.ExtractEquipReferenceNames(src);
+        if (used.Count == 0) return null;
+        var effectiveNames = await LoadEquipReferenceNamesAsync(db, equipmentId, ct);
+        return CheckEquipReferencesResolve(used, effectiveNames, equipmentId);
+    }

-        // The equipment↔Tag binding was retired in v3 (Tag is Raw-only), so no equipment-bound driver
-        // tags exist to derive an equipment tag base from. The {{equip}} token can't be resolved here.
-        var fullNames = Array.Empty<string>();
-        if (EquipmentScriptPaths.DeriveEquipmentBase(fullNames) is null)
+    /// <summary>
+    /// Scripted-alarm variant of <see cref="ValidateEquipTokenAsync"/>: validates <c>{{equip}}/&lt;RefName&gt;</c>
+    /// tokens in BOTH the predicate script AND the message template against the equipment's reference set —
+    /// the authoring mirror of the deploy gate, which covers all three (VT scripts, SA predicates, SA templates).
+    /// Keeps the editor⇔authoring⇔deploy invariant tight on the SA surface.
+    /// </summary>
+    private static async Task<UnsMutationResult?> ValidateEquipTokenForAlarmAsync(
+        OtOpcUaConfigDbContext db, string equipmentId, string? predicateScriptId, string? messageTemplate, CancellationToken ct)
+    {
+        var used = new HashSet<string>(StringComparer.Ordinal);
+        if (!string.IsNullOrEmpty(predicateScriptId))
        {
-            return new UnsMutationResult(false,
-                $"Equipment '{equipmentId}' has no single tag base, so the "
-                + $"{EquipmentScriptPaths.EquipToken} token can't be resolved. Add at least one driver tag under this "
-                + $"equipment (all sharing one object prefix), or remove {EquipmentScriptPaths.EquipToken} from the script.");
+            var src = await db.Scripts.Where(s => s.ScriptId == predicateScriptId)
+                .Select(s => s.SourceCode).FirstOrDefaultAsync(ct);
+            foreach (var u in EquipmentScriptPaths.ExtractEquipReferenceNames(src)) used.Add(u);
        }
-        return null;
+        foreach (var u in EquipmentScriptPaths.ExtractEquipReferenceNamesFromText(messageTemplate)) used.Add(u);
+        if (used.Count == 0) return null;
+        var effectiveNames = await LoadEquipReferenceNamesAsync(db, equipmentId, ct);
+        return CheckEquipReferencesResolve(used, effectiveNames, equipmentId);
+    }
+
+    /// <summary>The equipment's reference effective-name set: <c>DisplayNameOverride</c> else the backing raw
+    /// tag's <c>Name</c> (empty override treated as absent, matching <c>EquipmentReferenceMap.Build</c>), ordinal.</summary>
+    private static async Task<HashSet<string>> LoadEquipReferenceNamesAsync(
+        OtOpcUaConfigDbContext db, string equipmentId, CancellationToken ct)
+    {
+        var refs = await db.UnsTagReferences.AsNoTracking()
+            .Where(r => r.EquipmentId == equipmentId)
+            .Select(r => new { r.TagId, r.DisplayNameOverride })
+            .ToListAsync(ct);
+        var tagIds = refs.Select(r => r.TagId).ToList();
+        var tagNameById = await db.Tags.AsNoTracking()
+            .Where(t => tagIds.Contains(t.TagId))
+            .Select(t => new { t.TagId, t.Name })
+            .ToDictionaryAsync(t => t.TagId, t => t.Name, ct);
+        var effectiveNames = new HashSet<string>(StringComparer.Ordinal);
+        foreach (var r in refs)
+        {
+            var eff = string.IsNullOrEmpty(r.DisplayNameOverride)
+                ? (tagNameById.TryGetValue(r.TagId, out var n) ? n : null)
+                : r.DisplayNameOverride;
+            if (!string.IsNullOrEmpty(eff)) effectiveNames.Add(eff!);
+        }
+        return effectiveNames;
+    }
+
+    /// <summary>Names the unresolved <c>{{equip}}/&lt;RefName&gt;</c> tokens (or null when all resolve).</summary>
+    private static UnsMutationResult? CheckEquipReferencesResolve(
+        IReadOnlyCollection<string> used, HashSet<string> effectiveNames, string equipmentId)
+    {
+        var missing = used.Where(u => !effectiveNames.Contains(u)).ToList();
+        if (missing.Count == 0) return null;
+        return new UnsMutationResult(false,
+            $"Script uses {string.Join(", ", missing.Select(m => $"'{EquipmentScriptPaths.EquipTokenPrefix}{m}'"))} "
+            + $"but equipment '{equipmentId}' has no reference with that effective name. "
+            + "Add a matching reference on the Tags tab, or correct the script.");
    }

    /// <inheritdoc />
@@ -920,6 +1333,11 @@ public sealed class UnsTreeService(IDbContextFactory<OtOpcUaConfigDbContext> dbF
            return new UnsMutationResult(false, $"A virtual tag named '{input.Name}' already exists on this equipment.");
        }

+        // v3 Batch 3: the effective name must also be unique against this equipment's references + scripted
+        // alarms (they share the equipment's UNS NodeId space) — the authoring mirror of the deploy gate.
+        var nameGuard = await _guard.CheckAsync(equipmentId, input.Name, EffectiveNameSourceKind.VirtualTag, null, ct);
+        if (nameGuard is not null) return new UnsMutationResult(false, nameGuard);
+
        var equipGuard = await ValidateEquipTokenAsync(db, equipmentId, input.ScriptId, ct);
        if (equipGuard is not null) return equipGuard.Value;

@@ -969,6 +1387,10 @@ public sealed class UnsTreeService(IDbContextFactory<OtOpcUaConfigDbContext> dbF
            return new UnsMutationResult(false, $"A virtual tag named '{input.Name}' already exists on this equipment.");
        }

+        // v3 Batch 3: effective-name uniqueness across references + scripted alarms (excluding this VT).
+        var nameGuard = await _guard.CheckAsync(entity.EquipmentId, input.Name, EffectiveNameSourceKind.VirtualTag, virtualTagId, ct);
+        if (nameGuard is not null) return new UnsMutationResult(false, nameGuard);
+
        var equipGuard = await ValidateEquipTokenAsync(db, entity.EquipmentId, input.ScriptId, ct);
        if (equipGuard is not null) return equipGuard.Value;

@@ -1193,58 +1615,6 @@ public sealed class UnsTreeService(IDbContextFactory<OtOpcUaConfigDbContext> dbF
        return null;
    }

-    /// <summary>
-    /// An equipment may only bind to a driver in the same cluster as its line.
-    /// Policy:
-    /// <list type="bullet">
-    ///   <item>Driver-less (<c>DriverInstanceId</c> empty) → always allowed (returns <c>null</c>).</item>
-    ///   <item>Driver bound but the line/area does not resolve to a cluster → rejected (unresolvable
-    ///   line cannot guarantee cluster alignment, so the bind is unsafe).</item>
-    ///   <item>Driver bound, line resolves, clusters differ → rejected.</item>
-    ///   <item>Driver bound, line resolves, clusters match → allowed (returns <c>null</c>).</item>
-    /// </list>
-    /// </summary>
-    private static async Task<UnsMutationResult?> CheckDriverClusterGuardAsync(
-        OtOpcUaConfigDbContext db,
-        EquipmentInput input,
-        CancellationToken ct)
-    {
-        if (string.IsNullOrWhiteSpace(input.DriverInstanceId))
-        {
-            return null;
-        }
-
-        var line = await db.UnsLines.FirstOrDefaultAsync(l => l.UnsLineId == input.UnsLineId, ct);
-        var area = line is null ? null : await db.UnsAreas.FirstOrDefaultAsync(a => a.UnsAreaId == line.UnsAreaId, ct);
-        var lineCluster = area?.ClusterId;
-
-        if (lineCluster is null)
-        {
-            return new UnsMutationResult(
-                false,
-                $"Cannot bind driver '{input.DriverInstanceId}': UNS line '{input.UnsLineId}' does not resolve to a cluster (decision #122).");
-        }
-
-        var driverCluster = await db.DriverInstances
-            .Where(d => d.DriverInstanceId == input.DriverInstanceId)
-            .Select(d => d.ClusterId)
-            .FirstOrDefaultAsync(ct);
-
-        if (driverCluster is null)
-        {
-            return new UnsMutationResult(false, $"Driver '{input.DriverInstanceId}' not found.");
-        }
-
-        if (driverCluster != lineCluster)
-        {
-            return new UnsMutationResult(
-                false,
-                $"Driver '{input.DriverInstanceId}' is in cluster '{driverCluster}' but the line is in cluster '{lineCluster}' (decision #122).");
-        }
-
-        return null;
-    }
-
    /// <inheritdoc />
    public async Task<IReadOnlyList<EquipmentAlarmRow>> LoadAlarmsForEquipmentAsync(string equipmentId, CancellationToken ct = default)
    {
@@ -1277,6 +1647,14 @@ public sealed class UnsTreeService(IDbContextFactory<OtOpcUaConfigDbContext> dbF
        if (await db.ScriptedAlarms.AnyAsync(a => a.EquipmentId == equipmentId && a.Name == input.Name, ct))
            return new UnsMutationResult(false, $"A scripted alarm named '{input.Name}' already exists on this equipment.");

+        // v3 Batch 3: effective-name uniqueness across references + VirtualTags on this equipment.
+        var nameGuard = await _guard.CheckAsync(equipmentId, input.Name, EffectiveNameSourceKind.ScriptedAlarm, null, ct);
+        if (nameGuard is not null) return new UnsMutationResult(false, nameGuard);
+
+        // v3 Batch 3 (WP4): {{equip}}/<RefName> in the predicate script or message template must resolve.
+        var equipGuard = await ValidateEquipTokenForAlarmAsync(db, equipmentId, input.PredicateScriptId, input.MessageTemplate, ct);
+        if (equipGuard is not null) return equipGuard.Value;
+
        db.ScriptedAlarms.Add(new ScriptedAlarm
        {
            ScriptedAlarmId = input.ScriptedAlarmId,
@@ -1307,6 +1685,14 @@ public sealed class UnsTreeService(IDbContextFactory<OtOpcUaConfigDbContext> dbF
        if (await db.ScriptedAlarms.AnyAsync(a => a.EquipmentId == entity.EquipmentId && a.Name == input.Name && a.ScriptedAlarmId != scriptedAlarmId, ct))
            return new UnsMutationResult(false, $"A scripted alarm named '{input.Name}' already exists on this equipment.");

+        // v3 Batch 3: effective-name uniqueness across references + VirtualTags (excluding this alarm).
+        var nameGuard = await _guard.CheckAsync(entity.EquipmentId, input.Name, EffectiveNameSourceKind.ScriptedAlarm, scriptedAlarmId, ct);
+        if (nameGuard is not null) return new UnsMutationResult(false, nameGuard);
+
+        // v3 Batch 3 (WP4): {{equip}}/<RefName> in the predicate script or message template must resolve.
+        var equipGuard = await ValidateEquipTokenForAlarmAsync(db, entity.EquipmentId, input.PredicateScriptId, input.MessageTemplate, ct);
+        if (equipGuard is not null) return equipGuard.Value;
+
        db.Entry(entity).Property(e => e.RowVersion).OriginalValue = rowVersion;
        entity.Name = input.Name;
        entity.AlarmType = input.AlarmType;
@@ -10,6 +10,7 @@
        <FrameworkReference Include="Microsoft.AspNetCore.App"/>
        <PackageReference Include="Microsoft.AspNetCore.SignalR.Client"/>
        <PackageReference Include="ZB.MOM.WW.Theme"/>
+        <PackageReference Include="ZB.MOM.WW.Secrets.Ui"/>
    </ItemGroup>

    <ItemGroup>
@@ -23,6 +23,11 @@

    const KIND_MAP = { Method: 0, Field: 3, Property: 9, Event: 10, Class: 5, Module: 8, Variable: 4, Text: 18 };

+    // The owning-equipment id is stamped onto each editor's model at createEditor time so the globally
+    // registered csharp providers (which only receive the model) can thread it into the {{equip}}/<RefName>
+    // completion + diagnostics. Null on the shared ScriptEdit page (equip-ref features inert there).
+    function equipmentIdOf(model) { return (model && model.__otEquipmentId) || null; }
+
    function registerCSharpProviders() {
        monaco.languages.registerCompletionItemProvider("csharp", {
            triggerCharacters: [".", "(", "\""],
@@ -31,7 +36,7 @@
                    const resp = await fetch("/api/script-analysis/completions", {
                        method: "POST", credentials: "same-origin",
                        headers: { "Content-Type": "application/json" },
-                        body: JSON.stringify({ codeText: model.getValue(), line: position.lineNumber, column: position.column })
+                        body: JSON.stringify({ codeText: model.getValue(), line: position.lineNumber, column: position.column, equipmentId: equipmentIdOf(model) })
                    });
                    if (!resp.ok) return { suggestions: [] };
                    const data = await resp.json();
@@ -72,7 +77,7 @@
                    const resp = await fetch("/api/script-analysis/hover", {
                        method: "POST", credentials: "same-origin",
                        headers: { "Content-Type": "application/json" },
-                        body: JSON.stringify({ codeText: model.getValue(), line: position.lineNumber, column: position.column })
+                        body: JSON.stringify({ codeText: model.getValue(), line: position.lineNumber, column: position.column, equipmentId: equipmentIdOf(model) })
                    });
                    if (!resp.ok) return null;
                    const data = await resp.json();
@@ -149,7 +154,7 @@
            const resp = await fetch("/api/script-analysis/diagnostics", {
                method: "POST", credentials: "same-origin",
                headers: { "Content-Type": "application/json" },
-                body: JSON.stringify({ code: model.getValue() })
+                body: JSON.stringify({ code: model.getValue(), equipmentId: equipmentIdOf(model) })
            });
            if (!resp.ok) return [];
            const data = await resp.json();
@@ -192,6 +197,9 @@
            // inside ctx.GetTag("…") / ctx.SetVirtualTag("…") without requiring an explicit Ctrl+Space.
            quickSuggestions: { other: true, comments: false, strings: true }
        });
+        // Stamp the owning-equipment id on the model so the global csharp providers can thread it into the
+        // {{equip}}/<RefName> completion + diagnostics (null on the shared ScriptEdit page).
+        try { const m0 = editor.getModel(); if (m0) m0.__otEquipmentId = options.equipmentId || null; } catch (x) {}
        let diagTimer = null;
        const scheduleDiagnostics = function () {
            if (diagTimer) clearTimeout(diagTimer);
@@ -0,0 +1,102 @@
+using System.Net;
+using Microsoft.AspNetCore.Server.Kestrel.Core;
+
+namespace ZB.MOM.WW.OtOpcUa.Host.Configuration;
+
+/// <summary>
+///     One HTTP endpoint the host was asked to serve, parsed out of the configured URL list so it
+///     can be re-bound explicitly.
+/// </summary>
+/// <param name="Host">The host component as written — <c>+</c>, <c>*</c>, a hostname, or an IP.</param>
+/// <param name="Port">The port.</param>
+/// <param name="IsSecure">True when the URL used the <c>https</c> scheme.</param>
+public sealed record KestrelHttpBinding(string Host, int Port, bool IsSecure)
+{
+    /// <summary>
+    ///     Parses a semicolon-separated URL list (the <c>ASPNETCORE_URLS</c> / <c>urls</c> format)
+    ///     into bindings. Unparseable entries are skipped rather than throwing — a malformed URL
+    ///     must not take the process down at startup.
+    /// </summary>
+    /// <param name="urls">The configured URL list, or null/empty when none is configured.</param>
+    /// <returns>The parsed bindings, in the order given; empty when nothing is configured.</returns>
+    public static IReadOnlyList<KestrelHttpBinding> Parse(string? urls)
+    {
+        if (string.IsNullOrWhiteSpace(urls))
+            return [];
+
+        var result = new List<KestrelHttpBinding>();
+        foreach (var raw in urls.Split(';', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries))
+        {
+            // Uri cannot parse the "+"/"*" wildcard hosts Kestrel accepts, so substitute a
+            // placeholder host purely to get scheme/port out, then keep the original host token.
+            var isWildcard = raw.Contains("://+", StringComparison.Ordinal)
+                          || raw.Contains("://*", StringComparison.Ordinal);
+            var probe = isWildcard
+                ? raw.Replace("://+", "://placeholder", StringComparison.Ordinal)
+                     .Replace("://*", "://placeholder", StringComparison.Ordinal)
+                : raw;
+
+            if (!Uri.TryCreate(probe, UriKind.Absolute, out var uri))
+                continue;
+
+            var host = isWildcard
+                ? raw.Contains("://+", StringComparison.Ordinal) ? "+" : "*"
+                : uri.Host;
+
+            result.Add(new KestrelHttpBinding(host, uri.Port, uri.Scheme == Uri.UriSchemeHttps));
+        }
+
+        return result;
+    }
+
+    /// <summary>
+    ///     Parses the bare-port list format of <c>ASPNETCORE_HTTP_PORTS</c> / <c>HTTP_PORTS</c> (and
+    ///     the <c>HTTPS</c> variants) into wildcard (<c>+</c>, all-interfaces) bindings — the shape
+    ///     Kestrel itself gives those variables. Modern .NET base images (aspnet:8.0+) set
+    ///     <c>ASPNETCORE_HTTP_PORTS=8080</c> as the container default <b>instead of</b>
+    ///     <c>ASPNETCORE_URLS</c>, so a node that never sets <c>URLS</c> explicitly still has a real
+    ///     configured surface here that must be re-bound, not replaced with Kestrel's localhost:5000.
+    /// </summary>
+    /// <param name="ports">A <c>;</c>- or <c>,</c>-separated list of bare ports, or null/empty.</param>
+    /// <param name="isSecure">True to mark the parsed bindings <c>https</c> (the <c>HTTPS_PORTS</c> vars).</param>
+    /// <returns>One all-interfaces binding per parseable port; empty when nothing is configured.</returns>
+    public static IReadOnlyList<KestrelHttpBinding> ParsePorts(string? ports, bool isSecure)
+    {
+        if (string.IsNullOrWhiteSpace(ports))
+            return [];
+
+        var result = new List<KestrelHttpBinding>();
+        foreach (var token in ports.Split([';', ','], StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries))
+        {
+            // Skip a malformed port rather than throwing — a bad env var must not down startup.
+            if (int.TryParse(token, out var port) && port is > 0 and <= 65535)
+                result.Add(new KestrelHttpBinding("+", port, isSecure));
+        }
+
+        return result;
+    }
+
+    /// <summary>
+    ///     Applies this binding to Kestrel, choosing the narrowest listen call the host component
+    ///     allows.
+    /// </summary>
+    /// <remarks>
+    ///     A hostname that is neither a literal IP nor <c>localhost</c> cannot be reliably mapped to
+    ///     a local interface, so it falls back to <see cref="KestrelServerOptions.ListenAnyIP"/> —
+    ///     the safe superset. Narrowing it and guessing wrong would silently stop serving.
+    /// </remarks>
+    /// <param name="options">The Kestrel options being configured.</param>
+    public void Apply(KestrelServerOptions options)
+    {
+        ArgumentNullException.ThrowIfNull(options);
+
+        if (Host is "+" or "*")
+            options.ListenAnyIP(Port);
+        else if (IPAddress.TryParse(Host, out var address))
+            options.Listen(address, Port);
+        else if (string.Equals(Host, "localhost", StringComparison.OrdinalIgnoreCase))
+            options.ListenLocalhost(Port);
+        else
+            options.ListenAnyIP(Port);
+    }
+}
@@ -0,0 +1,101 @@
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.DependencyInjection;
+using ZB.MOM.WW.LocalDb;
+using ZB.MOM.WW.LocalDb.Replication;
+using ZB.MOM.WW.OtOpcUa.Runtime.DeploymentCache;
+
+namespace ZB.MOM.WW.OtOpcUa.Host.Configuration;
+
+/// <summary>
+///     Single registration point for the node-local LocalDb subsystem: the embedded SQLite store
+///     that caches the deployed-configuration artifact, plus the optional gRPC replication that
+///     mirrors it to the node's redundant pair peer.
+/// </summary>
+/// <remarks>
+///     <para>
+///         Exists as a named extension rather than inline <c>AddZbLocalDb</c> calls in
+///         <c>Program.cs</c> so the wiring is covered by a DI resolution test — <c>Program.cs</c> is
+///         top-level statements and cannot be exercised directly, which is exactly how a
+///         "registered but never resolvable" defect ships unnoticed. This family has shipped that
+///         defect three times (Secrets 0.2.0, Secrets 0.2.2, ScadaBridge #22).
+///     </para>
+///     <para>
+///         <b>Driver-role nodes only.</b> Admin-only nodes have no deployed configuration to cache,
+///         and registering here would impose the <c>LocalDb:Path</c>-required-or-no-boot constraint
+///         on them for nothing.
+///     </para>
+///     <para>
+///         <b>Storage is unconditional; replication is default-OFF.</b> A node with no
+///         <c>PeerAddress</c> and no <c>SyncListenPort</c> is simply a fast local SQLite file —
+///         <c>AddZbLocalDbReplication</c> registers the engine but it stays idle. Replication is
+///         opt-in per pair because there is no production distribution story for the sync
+///         <c>ApiKey</c> yet (the same open question the Secrets KEK has).
+///     </para>
+/// </remarks>
+public static class LocalDbRegistration
+{
+    /// <summary>Configuration section holding <c>LocalDbOptions</c>.</summary>
+    public const string LocalDbSectionPath = "LocalDb";
+
+    /// <summary>Configuration section holding <c>ReplicationOptions</c>.</summary>
+    public const string ReplicationSectionPath = "LocalDb:Replication";
+
+    /// <summary>
+    ///     Configuration key carrying the dedicated h2c sync listener's port. Zero or absent means
+    ///     no listener is bound and the passive sync endpoint is not mapped.
+    /// </summary>
+    public const string SyncListenPortKey = "LocalDb:SyncListenPort";
+
+    /// <summary>
+    ///     The port the dedicated cleartext-HTTP/2 sync listener should bind, or <c>0</c> when the
+    ///     node should not listen at all. Defaults to <c>0</c> — absent configuration must mean
+    ///     "off".
+    /// </summary>
+    /// <param name="configuration">The application configuration.</param>
+    /// <returns>The configured sync port, or <c>0</c>.</returns>
+    public static int SyncListenPort(IConfiguration configuration)
+    {
+        ArgumentNullException.ThrowIfNull(configuration);
+        return configuration.GetValue(SyncListenPortKey, defaultValue: 0);
+    }
+
+    /// <summary>
+    ///     Registers the local database (with the deployment-cache schema applied and registered for
+    ///     replication) and the replication engine.
+    /// </summary>
+    /// <remarks>
+    ///     <para>
+    ///         <see cref="LocalDbSetup.OnReady"/> runs inside <c>AddZbLocalDb</c>'s singleton factory,
+    ///         before the first caller receives the <c>ILocalDb</c> — so every consumer is guaranteed
+    ///         to see the tables created and their capture triggers installed.
+    ///     </para>
+    ///     <para>
+    ///         <c>AddZbLocalDbReplication</c> is called unconditionally rather than behind an
+    ///         <c>Enabled</c> flag because the library already models "off" as "no
+    ///         <c>PeerAddress</c>": the initiator background service idles and the passive endpoint
+    ///         is only reachable if <c>Program.cs</c> maps it, which it does only when
+    ///         <see cref="SyncListenPortKey"/> is set. Adding a second gate on top would give two
+    ///         ways to express the same thing and a way for them to disagree.
+    ///     </para>
+    /// </remarks>
+    /// <param name="services">The service collection to add to.</param>
+    /// <param name="configuration">The application configuration.</param>
+    /// <returns>The same <paramref name="services"/> instance, for chaining.</returns>
+    public static IServiceCollection AddOtOpcUaLocalDb(
+        this IServiceCollection services,
+        IConfiguration configuration)
+    {
+        ArgumentNullException.ThrowIfNull(services);
+        ArgumentNullException.ThrowIfNull(configuration);
+
+        services.AddZbLocalDb(configuration, LocalDbSetup.OnReady);
+        services.AddZbLocalDbReplication(configuration);
+
+        // The consumer-facing seam. WithOtOpcUaRuntimeActors resolves this optionally and threads it
+        // into DriverHostActor; registering the store without this leaves the cache tables present,
+        // replicating, and never written to.
+        services.AddSingleton<IDeploymentArtifactCache, LocalDbDeploymentArtifactCache>();
+
+        return services;
+    }
+}
@@ -0,0 +1,48 @@
+using ZB.MOM.WW.LocalDb;
+using ZB.MOM.WW.OtOpcUa.Runtime.DeploymentCache;
+
+namespace ZB.MOM.WW.OtOpcUa.Host.Configuration;
+
+/// <summary>
+///     The <c>onReady</c> callback handed to <c>AddZbLocalDb</c>: creates the deployment-cache
+///     tables and opts them into replication.
+/// </summary>
+/// <remarks>
+///     <para>
+///         Public rather than internal only so <c>LocalDbSetupTests</c> can drive the production
+///         callback directly. Initialising a test database from a hand-written copy of this schema
+///         would prove only that the test agrees with itself — the whole value of those tests is
+///         that they exercise <b>this</b> method.
+///     </para>
+/// </remarks>
+public static class LocalDbSetup
+{
+    /// <summary>
+    ///     Initialises the local database: DDL first, then replication registration.
+    /// </summary>
+    /// <remarks>
+    ///     <para>
+    ///         <b>THE ORDER IS LOAD-BEARING: DDL → RegisterReplicated → writes.</b>
+    ///         <c>RegisterReplicated</c> is what installs the three AFTER triggers that capture
+    ///         changes into the oplog. Any row written before that call is never captured, so it
+    ///         never reaches the peer — silently, and permanently, because nothing ever revisits
+    ///         history. Phase 1 writes nothing here; when Phase 2 adds its store-and-forward
+    ///         migrator, the migrator must run <i>after</i> both registrations for the same reason.
+    ///     </para>
+    /// </remarks>
+    /// <param name="db">The freshly constructed local database.</param>
+    public static void OnReady(ILocalDb db)
+    {
+        ArgumentNullException.ThrowIfNull(db);
+
+        // CreateConnection() hands back an already-open, pragma-configured connection carrying the
+        // zb_hlc_next() UDF the capture triggers need. Calling Open() on it would throw.
+        using (var connection = db.CreateConnection())
+        {
+            DeploymentCacheSchema.Apply(connection);
+        }
+
+        db.RegisterReplicated(DeploymentCacheSchema.ArtifactsTable);
+        db.RegisterReplicated(DeploymentCacheSchema.PointerTable);
+    }
+}
@@ -0,0 +1,162 @@
+using System.Security.Cryptography;
+using System.Text;
+using Grpc.Core;
+using Grpc.Core.Interceptors;
+using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Options;
+using ZB.MOM.WW.LocalDb.Replication;
+
+namespace ZB.MOM.WW.OtOpcUa.Host.Configuration;
+
+/// <summary>
+///     Gates the LocalDb passive sync endpoint. The replication library deliberately leaves inbound
+///     authentication to the host — its <c>LocalDbSyncService</c> verifies nothing — so without this
+///     interceptor anything that can reach a driver node's sync port could stream arbitrary rows
+///     into that node's deployment-artifact cache.
+/// </summary>
+/// <remarks>
+///     <para>
+///         <b>Why that matters here specifically.</b> The cached artifact is what a driver node
+///         boots from when central SQL is unreachable. An attacker able to write it could choose
+///         the configuration a node comes up on during exactly the outage nobody is watching.
+///     </para>
+///     <para>
+///         <b>Scoped by method path.</b> Only calls under <c>/localdb_sync.v1.LocalDbSync/</c> are
+///         gated; every other method on the shared gRPC pipeline passes through untouched.
+///     </para>
+///     <para>
+///         <b>Fail-closed.</b> With no <c>LocalDb:Replication:ApiKey</c> configured, NO sync stream
+///         is accepted, authenticated or not. That is the deliberate choice: the alternative —
+///         treating "no key" as "no auth required" — would silently expose the endpoint on exactly
+///         the default configuration every node ships with. An operator enabling replication must
+///         set the same key on both nodes of the pair, which is already required for the initiator
+///         to dial out (<c>SyncBackgroundService</c> sends <c>Authorization: Bearer &lt;key&gt;</c>).
+///         A key typo therefore stops convergence outright rather than degrading to unauthenticated.
+///     </para>
+///     <para>
+///         Comparison is <see cref="CryptographicOperations.FixedTimeEquals"/> over UTF-8 bytes, so
+///         a wrong key cannot be recovered byte-by-byte from response timing. Length differences are
+///         unavoidably observable and are not sensitive.
+///     </para>
+/// </remarks>
+public sealed class LocalDbSyncAuthInterceptor : Interceptor
+{
+    private const string ServicePrefix = "/localdb_sync.v1.LocalDbSync/";
+    private const string AuthorizationHeader = "authorization";
+    private const string BearerPrefix = "Bearer ";
+
+    private readonly IOptions<ReplicationOptions> _options;
+    private readonly ILogger<LocalDbSyncAuthInterceptor> _logger;
+
+    /// <summary>Creates the interceptor.</summary>
+    /// <param name="options">Replication options; <c>ApiKey</c> is the expected bearer token.</param>
+    /// <param name="logger">Logger for denial diagnostics.</param>
+    public LocalDbSyncAuthInterceptor(
+        IOptions<ReplicationOptions> options,
+        ILogger<LocalDbSyncAuthInterceptor> logger)
+    {
+        ArgumentNullException.ThrowIfNull(options);
+        ArgumentNullException.ThrowIfNull(logger);
+
+        _options = options;
+        _logger = logger;
+    }
+
+    /// <inheritdoc />
+    public override Task<TResponse> UnaryServerHandler<TRequest, TResponse>(
+        TRequest request,
+        ServerCallContext context,
+        UnaryServerMethod<TRequest, TResponse> continuation)
+    {
+        Authorize(context);
+        return continuation(request, context);
+    }
+
+    /// <inheritdoc />
+    public override Task DuplexStreamingServerHandler<TRequest, TResponse>(
+        IAsyncStreamReader<TRequest> requestStream,
+        IServerStreamWriter<TResponse> responseStream,
+        ServerCallContext context,
+        DuplexStreamingServerMethod<TRequest, TResponse> continuation)
+    {
+        Authorize(context);
+        return continuation(requestStream, responseStream, context);
+    }
+
+    /// <inheritdoc />
+    public override Task<TResponse> ClientStreamingServerHandler<TRequest, TResponse>(
+        IAsyncStreamReader<TRequest> requestStream,
+        ServerCallContext context,
+        ClientStreamingServerMethod<TRequest, TResponse> continuation)
+    {
+        Authorize(context);
+        return continuation(requestStream, context);
+    }
+
+    /// <inheritdoc />
+    public override Task ServerStreamingServerHandler<TRequest, TResponse>(
+        TRequest request,
+        IServerStreamWriter<TResponse> responseStream,
+        ServerCallContext context,
+        ServerStreamingServerMethod<TRequest, TResponse> continuation)
+    {
+        Authorize(context);
+        return continuation(request, responseStream, context);
+    }
+
+    /// <summary>
+    ///     Throws <see cref="RpcException"/> with <see cref="StatusCode.PermissionDenied"/> if this
+    ///     is a sync call that does not carry the configured bearer token. Non-sync calls return
+    ///     immediately.
+    /// </summary>
+    private void Authorize(ServerCallContext context)
+    {
+        if (!context.Method.StartsWith(ServicePrefix, StringComparison.Ordinal))
+            return;
+
+        var expected = _options.Value.ApiKey;
+        if (string.IsNullOrEmpty(expected))
+        {
+            _logger.LogWarning(
+                "Rejected a LocalDb sync call to {Method}: no LocalDb:Replication:ApiKey is configured, " +
+                "so the passive sync endpoint is closed. Configure the same key on both nodes of the pair.",
+                context.Method);
+            throw new RpcException(new Status(
+                StatusCode.PermissionDenied,
+                "LocalDb sync is not accepting connections: no API key is configured on this node."));
+        }
+
+        var presented = ExtractBearerToken(context.RequestHeaders);
+        if (presented is null || !FixedTimeEquals(presented, expected))
+        {
+            _logger.LogWarning(
+                "Rejected a LocalDb sync call to {Method}: {Reason}.",
+                context.Method,
+                presented is null ? "no bearer token presented" : "bearer token did not match");
+            throw new RpcException(new Status(
+                StatusCode.PermissionDenied,
+                "LocalDb sync authentication failed."));
+        }
+    }
+
+    private static string? ExtractBearerToken(Metadata headers)
+    {
+        // gRPC lowercases header keys on the wire; compare case-insensitively anyway so a
+        // hand-built Metadata in a test behaves the same as a real request.
+        foreach (var entry in headers)
+        {
+            if (!string.Equals(entry.Key, AuthorizationHeader, StringComparison.OrdinalIgnoreCase))
+                continue;
+
+            var value = entry.Value;
+            if (value is not null && value.StartsWith(BearerPrefix, StringComparison.OrdinalIgnoreCase))
+                return value[BearerPrefix.Length..];
+        }
+
+        return null;
+    }
+
+    private static bool FixedTimeEquals(string presented, string expected)
+        => CryptographicOperations.FixedTimeEquals(
+            Encoding.UTF8.GetBytes(presented), Encoding.UTF8.GetBytes(expected));
+}
@@ -0,0 +1,55 @@
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+using ZB.MOM.WW.Secrets.Abstractions;
+
+namespace ZB.MOM.WW.OtOpcUa.Host.Configuration;
+
+/// <summary>
+///     Forces this node's secret-replication actor into existence at startup.
+/// </summary>
+/// <remarks>
+///     <para>
+///         The replication actor is created <b>lazily</b>, on the first resolution of
+///         <see cref="ISecretStore"/> — resolving the store builds <c>ReplicatingSecretStore</c>,
+///         which takes <c>ISecretReplicator</c>, whose factory touches
+///         <c>SecretReplicationActorProvider.ActorRef</c> and thereby spawns the actor.
+///     </para>
+///     <para>
+///         Laziness is correct for the library (the <c>ActorSystem</c> is usually registered after
+///         the replication call), but it makes participation in anti-entropy accidental: a node that
+///         happens never to read or write a secret — a plausible steady state for a driver-role node
+///         whose driver configs carry no <c>${secret:}</c> references — would never create the actor,
+///         never announce its manifest, and never converge. Nothing would fail; it would just
+///         silently not replicate. Resolving the store once at startup makes participation
+///         unconditional.
+///     </para>
+///     <para>
+///         <b>History — this hook has met two library defects, both fixed.</b> Against 0.2.0 it was
+///         inert: the package never bound its own <c>ISecretReplicator</c> (TryAdd registration
+///         order), so this resolve built a <c>ReplicatingSecretStore</c> around a no-op sink and
+///         spawned no actor. Against 0.2.1 it was worse: the resolve <b>deadlocked the host at
+///         startup</b> — the package's DI graph had a circular singleton dependency, invisible to
+///         the container through factory lambdas (scadaproj#1). Fixed in 0.2.2 by deferring the
+///         cycle-closing invalidator edge;
+///         <c>SecretsReplicationRegistrationTests.The_startup_hook_actually_creates_the_replication_actor</c>
+///         exercises this hook against a built provider on a real single-node cluster.
+///     </para>
+/// </remarks>
+/// <param name="services">Root provider used to resolve the (decorated) secret store exactly once.</param>
+public sealed class SecretReplicationStarter(IServiceProvider services) : IHostedService
+{
+    /// <summary>Resolves <see cref="ISecretStore"/>, which spawns the replication actor.</summary>
+    /// <param name="cancellationToken">Unused — resolution is synchronous and non-blocking.</param>
+    /// <returns>A completed task.</returns>
+    public Task StartAsync(CancellationToken cancellationToken)
+    {
+        // The resolution itself is the side effect; the instance is deliberately unused.
+        _ = services.GetRequiredService<ISecretStore>();
+        return Task.CompletedTask;
+    }
+
+    /// <summary>No-op: the actor's lifetime is the actor system's.</summary>
+    /// <param name="cancellationToken">Unused.</param>
+    /// <returns>A completed task.</returns>
+    public Task StopAsync(CancellationToken cancellationToken) => Task.CompletedTask;
+}
@@ -0,0 +1,82 @@
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+using ZB.MOM.WW.Secrets.DependencyInjection;
+using ZB.MOM.WW.Secrets.Replicator.AkkaDotNet.DependencyInjection;
+
+namespace ZB.MOM.WW.OtOpcUa.Host.Configuration;
+
+/// <summary>
+///     Single registration point for the secrets subsystem on every OtOpcUa node, admin- and
+///     driver-role alike. Exists as a named extension rather than an inline <c>AddZbSecrets</c> call
+///     in <c>Program.cs</c> so the choice of <c>ISecretStore</c> implementation is covered by a DI
+///     resolution test — <c>Program.cs</c> is top-level statements and cannot be exercised directly,
+///     which is exactly how a "registered but never resolvable" wiring defect ships unnoticed.
+/// </summary>
+public static class SecretsRegistration
+{
+    /// <summary>Configuration key gating cluster secret replication. Absent or false = off.</summary>
+    public const string ReplicationEnabledKey = "Secrets:Replication:Enabled";
+
+    /// <summary>Configuration section holding <c>AkkaSecretsReplicationOptions</c>.</summary>
+    public const string ReplicationSectionPath = "Secrets:Replication";
+
+    /// <summary>Configuration section holding the core secrets options.</summary>
+    public const string SecretsSectionPath = "Secrets";
+
+    /// <summary>
+    ///     True when cluster secret replication is switched on in configuration. Defaults to false —
+    ///     absent configuration must mean "off".
+    /// </summary>
+    /// <param name="configuration">The application configuration.</param>
+    /// <returns><c>true</c> when replication is enabled.</returns>
+    public static bool IsReplicationEnabled(IConfiguration configuration)
+    {
+        ArgumentNullException.ThrowIfNull(configuration);
+        return configuration.GetValue(ReplicationEnabledKey, defaultValue: false);
+    }
+
+    /// <summary>
+    ///     Registers the secrets subsystem. Replication is <b>opt-in</b>: unless
+    ///     <see cref="ReplicationEnabledKey"/> is true this is exactly the plain local SQLite wiring
+    ///     the host has always used.
+    /// </summary>
+    /// <remarks>
+    ///     <para>
+    ///         The gate is deliberately default-deny. This call decides which <c>ISecretStore</c> the
+    ///         container hands to <b>every</b> node, including driver-role nodes with no auth or
+    ///         AdminUI surface, where a bad store surfaces as drivers failing to open sessions rather
+    ///         than as a failing test. Enabling replication by default would change secret resolution
+    ///         across a production fleet with nobody having asked for it.
+    ///     </para>
+    ///     <para>
+    ///         <c>AddZbSecretsAkkaReplication</c> calls <c>AddZbSecrets</c> internally, so the two
+    ///         branches are alternatives, never additive — calling both would double-register.
+    ///     </para>
+    /// </remarks>
+    /// <param name="services">The service collection to add to.</param>
+    /// <param name="configuration">The application configuration.</param>
+    /// <returns>The same <paramref name="services"/> instance, for chaining.</returns>
+    public static IServiceCollection AddOtOpcUaSecrets(
+        this IServiceCollection services,
+        IConfiguration configuration)
+    {
+        ArgumentNullException.ThrowIfNull(services);
+        ArgumentNullException.ThrowIfNull(configuration);
+
+        if (!IsReplicationEnabled(configuration))
+        {
+            services.AddZbSecrets(configuration, SecretsSectionPath);
+            return services;
+        }
+
+        services.AddZbSecretsAkkaReplication(configuration, SecretsSectionPath, ReplicationSectionPath);
+
+        // Anti-entropy participation must not hinge on this node happening to touch a secret — see
+        // SecretReplicationStarter for why the library's lazy actor creation is insufficient here.
+        services.AddSingleton<SecretReplicationStarter>();
+        services.AddHostedService(sp => sp.GetRequiredService<SecretReplicationStarter>());
+
+        return services;
+    }
+}
@@ -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.Core.Resilience;
+using ZB.MOM.WW.Secrets.Abstractions;

 namespace ZB.MOM.WW.OtOpcUa.Host.Drivers;

@@ -48,7 +49,10 @@ public static class DriverFactoryBootstrap
            // The calc driver needs the root script logger so a script failure fans out onto the
            // script-logs topic; resolve it here (null on nodes without the script pipeline wired).
            var scriptRoot = sp.GetService<ZB.MOM.WW.OtOpcUa.Core.Scripting.ScriptRootLogger>();
-            Register(registry, loggerFactory, scriptRoot);
+            // The Galaxy driver resolves its Gateway.ApiKeySecretRef secret: arm through the
+            // shared ISecretResolver (registered unconditionally by AddZbSecrets on every node).
+            var secretResolver = sp.GetRequiredService<ISecretResolver>();
+            Register(registry, loggerFactory, secretResolver, scriptRoot);
            return registry;
        });
        services.AddSingleton<IDriverFactory>(sp =>
@@ -131,15 +135,16 @@ public static class DriverFactoryBootstrap
    private static void Register(
        DriverFactoryRegistry registry,
        ILoggerFactory? loggerFactory,
+        ISecretResolver secretResolver,
        ZB.MOM.WW.OtOpcUa.Core.Scripting.ScriptRootLogger? scriptRoot = null)
    {
        Driver.AbCip.AbCipDriverFactoryExtensions.Register(registry);
        Driver.AbLegacy.AbLegacyDriverFactoryExtensions.Register(registry, loggerFactory);
        Driver.Calculation.CalculationDriverFactoryExtensions.Register(registry, loggerFactory, scriptRoot);
        Driver.FOCAS.FocasDriverFactoryExtensions.Register(registry);
-        Driver.Galaxy.GalaxyDriverFactoryExtensions.Register(registry, loggerFactory);
+        Driver.Galaxy.GalaxyDriverFactoryExtensions.Register(registry, secretResolver, loggerFactory);
        Driver.Modbus.ModbusDriverFactoryExtensions.Register(registry, loggerFactory);
-        Driver.OpcUaClient.OpcUaClientDriverFactoryExtensions.Register(registry, loggerFactory);
+        Driver.OpcUaClient.OpcUaClientDriverFactoryExtensions.Register(registry, loggerFactory, secretResolver);
        Driver.S7.S7DriverFactoryExtensions.Register(registry);
        Driver.TwinCAT.TwinCATDriverFactoryExtensions.Register(registry);
    }
@@ -1,10 +1,15 @@
 using Microsoft.AspNetCore.Routing;
 using Microsoft.EntityFrameworkCore;
+using Microsoft.Extensions.Configuration;
 using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Diagnostics.HealthChecks;
+using Microsoft.Extensions.Options;
 using ZB.MOM.WW.Health;
 using ZB.MOM.WW.Health.Akka;
 using ZB.MOM.WW.Health.EntityFrameworkCore;
+using ZB.MOM.WW.LocalDb.Replication;
 using ZB.MOM.WW.OtOpcUa.Configuration;
+using ZB.MOM.WW.OtOpcUa.Host.Configuration;

 namespace ZB.MOM.WW.OtOpcUa.Host.Health;

@@ -36,7 +41,20 @@ public static class HealthEndpoints
                "admin-leader",
                failureStatus: null,
                tags: new[] { ZbHealthTags.Active },
-                args: "admin");
+                args: "admin")
+            // Registered unconditionally, not driver-gated. AddOtOpcUaHealth takes no role argument
+            // and runs on every node; the check itself resolves ISyncStatus optionally and reports
+            // Healthy when LocalDb is absent (admin-only graphs) or replication is default-OFF, so a
+            // plain node is never degraded by it. A factory registration keeps this no-arg signature
+            // while still reading ISyncStatus + options + the sync port from the container.
+            .Add(new HealthCheckRegistration(
+                "localdb-replication",
+                sp => new LocalDbReplicationHealthCheck(
+                    sp.GetService<ISyncStatus>(),
+                    sp.GetRequiredService<IOptions<ReplicationOptions>>(),
+                    LocalDbRegistration.SyncListenPort(sp.GetRequiredService<IConfiguration>())),
+                failureStatus: null,
+                tags: new[] { ZbHealthTags.Active }));
        return services;
    }

@@ -0,0 +1,126 @@
+using Microsoft.Extensions.Diagnostics.HealthChecks;
+using Microsoft.Extensions.Options;
+using ZB.MOM.WW.LocalDb.Replication;
+
+namespace ZB.MOM.WW.OtOpcUa.Host.Health;
+
+/// <summary>
+///     Pure decision function for the LocalDb replication probe, factored out of
+///     <see cref="LocalDbReplicationHealthCheck"/> so the whole matrix is table-testable without
+///     standing up a replication engine.
+/// </summary>
+public static class LocalDbReplicationDecision
+{
+    /// <summary>
+    ///     Maps the resolved replication facts to a health status.
+    /// </summary>
+    /// <param name="peerConfigured">
+    ///     True when this node participates in replication at all — it has a peer address to dial, or
+    ///     a sync listener bound. False means default-OFF, and default-OFF must never degrade a node.
+    /// </param>
+    /// <param name="connected">Whether a sync session is currently running.</param>
+    /// <param name="oplogBacklog">
+    ///     The unacked oplog backlog, or <see langword="null"/> when it could not be read. Null is
+    ///     deliberately not treated as zero: a failed poll is "unknown", not "caught up".
+    /// </param>
+    /// <param name="degradedThreshold">
+    ///     Backlog at or above which a connected pair is judged to be falling behind.
+    /// </param>
+    /// <returns>The status plus a human-readable reason.</returns>
+    public static (HealthStatus Status, string Description) Evaluate(
+        bool peerConfigured, bool connected, long? oplogBacklog, long degradedThreshold)
+    {
+        if (!peerConfigured)
+            return (HealthStatus.Healthy, "LocalDb replication is not configured on this node (default-OFF).");
+
+        if (!connected)
+            return (HealthStatus.Degraded, "LocalDb replication is configured but no sync session is connected.");
+
+        if (oplogBacklog is null)
+            return (HealthStatus.Degraded, "LocalDb replication is connected but its oplog backlog is unknown (the poll failed).");
+
+        if (oplogBacklog.Value >= degradedThreshold)
+            return (HealthStatus.Degraded,
+                $"LocalDb replication is connected but its oplog backlog ({oplogBacklog.Value}) is at or above the degraded threshold ({degradedThreshold}).");
+
+        return (HealthStatus.Healthy, $"LocalDb replication is connected; oplog backlog {oplogBacklog.Value}.");
+    }
+}
+
+/// <summary>
+///     Reports the health of this node's LocalDb replication link. Registered unconditionally with
+///     the shared health pipeline; when LocalDb is not present at all (admin-only graphs) it reports
+///     <see cref="HealthStatus.Healthy"/> rather than degrading — matching the
+///     <c>ActiveNodeHealthCheck</c> precedent of "not applicable ⇒ Healthy".
+/// </summary>
+/// <remarks>
+///     A node running LocalDb with replication switched off (no peer, no listener) is also Healthy:
+///     that is the default posture for most of the fleet, and it must not look degraded. Only a node
+///     that is <i>meant</i> to be replicating and is not — or is connected but cannot confirm it is
+///     draining — is surfaced as Degraded. It never reports Unhealthy: a replication problem does not
+///     stop the node serving its address space, so it must not fail a readiness gate.
+/// </remarks>
+public sealed class LocalDbReplicationHealthCheck : IHealthCheck
+{
+    /// <summary>
+    ///     Backlog at or above which a connected pair is reported Degraded. Well below the library's
+    ///     <c>MaxOplogRows</c> default (1,000,000, where a snapshot resync is forced), so the probe
+    ///     flags a pair that is falling behind long before the engine itself intervenes.
+    /// </summary>
+    public const long DefaultBacklogDegradedThreshold = 100_000;
+
+    private readonly ISyncStatus? _syncStatus;
+    private readonly ReplicationOptions _options;
+    private readonly int _syncListenPort;
+    private readonly long _degradedThreshold;
+
+    /// <summary>Creates the health check.</summary>
+    /// <param name="syncStatus">
+    ///     The replication status singleton, or <see langword="null"/> when the replication engine is
+    ///     not registered (admin-only nodes) — in which case the check is a Healthy no-op.
+    /// </param>
+    /// <param name="options">The bound replication options (peer address, etc.).</param>
+    /// <param name="syncListenPort">
+    ///     The configured sync listener port; a value greater than zero counts as "replication
+    ///     configured" even when this node is the passive side with no peer address.
+    /// </param>
+    /// <param name="degradedThreshold">Backlog degraded threshold; defaults to <see cref="DefaultBacklogDegradedThreshold"/>.</param>
+    public LocalDbReplicationHealthCheck(
+        ISyncStatus? syncStatus,
+        IOptions<ReplicationOptions> options,
+        int syncListenPort,
+        long degradedThreshold = DefaultBacklogDegradedThreshold)
+    {
+        ArgumentNullException.ThrowIfNull(options);
+
+        _syncStatus = syncStatus;
+        _options = options.Value;
+        _syncListenPort = syncListenPort;
+        _degradedThreshold = degradedThreshold;
+    }
+
+    /// <inheritdoc />
+    public Task<HealthCheckResult> CheckHealthAsync(
+        HealthCheckContext context, CancellationToken cancellationToken = default)
+    {
+        // No replication engine registered at all → not applicable → Healthy. Admin-only nodes and
+        // any graph that did not call AddOtOpcUaLocalDb land here.
+        if (_syncStatus is null)
+            return Task.FromResult(HealthCheckResult.Healthy(
+                "LocalDb replication is not present on this node."));
+
+        var peerConfigured =
+            !string.IsNullOrWhiteSpace(_options.PeerAddress) || _syncListenPort > 0;
+
+        var (status, description) = LocalDbReplicationDecision.Evaluate(
+            peerConfigured, _syncStatus.Connected, _syncStatus.OplogBacklog, _degradedThreshold);
+
+        var result = status switch
+        {
+            HealthStatus.Healthy => HealthCheckResult.Healthy(description),
+            _ => HealthCheckResult.Degraded(description),
+        };
+
+        return Task.FromResult(result);
+    }
+}
@@ -1,4 +1,5 @@
 using Microsoft.Extensions.Configuration;
+using ZB.MOM.WW.LocalDb.Replication;
 using ZB.MOM.WW.OtOpcUa.Commons.Observability;
 using ZB.MOM.WW.Telemetry;

@@ -27,7 +28,11 @@ public static class ObservabilityExtensions
        return services.AddZbTelemetry(o =>
        {
            o.ServiceName = "otopcua";
-            o.Meters = [OtOpcUaTelemetry.MeterName];
+            // o.Meters is a STRICT allowlist — ZbTelemetry adds only the named meters, with no
+            // wildcard. The LocalDb replication engine publishes under its own meter name, so
+            // without this entry its localdb.sync.* / localdb.oplog.depth series are silently absent
+            // from /metrics on driver nodes (the exact omission a ScadaBridge live gate caught).
+            o.Meters = [OtOpcUaTelemetry.MeterName, LocalDbMetrics.MeterName];
            o.ActivitySources = [OtOpcUaTelemetry.ActivitySourceName];
            if (Enum.TryParse<ZbExporter>(configuration["OtOpcUa:Telemetry:Exporter"], ignoreCase: true, out var exporter))
                o.Exporter = exporter;
@@ -1,7 +1,9 @@
 using Akka.Actor;
 using Akka.Hosting;
+using Microsoft.AspNetCore.Server.Kestrel.Core;
 using Microsoft.Extensions.DependencyInjection.Extensions;
 using Serilog;
+using ZB.MOM.WW.LocalDb.Replication;
 using Serilog.Events;
 using ZB.MOM.WW.OtOpcUa.AdminUI;
 using ZB.MOM.WW.OtOpcUa.AdminUI.Clients;
@@ -37,6 +39,12 @@ using ZB.MOM.WW.OtOpcUa.Security.Ldap;
 using ZB.MOM.WW.Configuration;
 using ZB.MOM.WW.Telemetry.Serilog;
 using ZB.MOM.WW.OtOpcUa.AdminUI.Api;
+using Microsoft.Extensions.DependencyInjection;
+using ZB.MOM.WW.Secrets.Abstractions;
+using ZB.MOM.WW.Secrets.Configuration;
+using ZB.MOM.WW.Secrets.DependencyInjection;
+using ZB.MOM.WW.Secrets.Replicator.AkkaDotNet;
+using ZB.MOM.WW.Secrets.Sqlite;

 // Roles drive the entire conditional wiring below — see ZB.MOM.WW.OtOpcUa.Cluster.RoleParser.
 var roles = RoleParser.Parse(Environment.GetEnvironmentVariable("OTOPCUA_ROLES"));
@@ -72,6 +80,27 @@ if (roleSuffix is not null)
    builder.Configuration.AddCommandLine(args);
 }

+// Pre-host ${secret:} expansion: rewrites ${secret:name} tokens in the assembled configuration
+// BEFORE the host is built, so every downstream binder/validator sees resolved plaintext.
+// Placement matters: this runs AFTER all config providers are assembled (base appsettings, the
+// role overlay, and the env-vars + command-line re-append above) but BEFORE anything READS a
+// config value (AddZbSerilog's ReadFrom.Configuration, AddOtOpcUaConfigDb, and the first
+// ValidateOnStart bind all follow). With no ${secret:} tokens present this is a no-op pass;
+// it also migrates the secrets SQLite store on startup.
+// ASP0000: DELIBERATE throwaway container — expansion must run before builder.Build(), so it
+// cannot use the app's DI. Fully disposed here; shares no singletons with the host container.
+#pragma warning disable ASP0000
+await using (var secretsProvider = new ServiceCollection()
+    .AddZbSecrets(builder.Configuration, "Secrets")
+    .BuildServiceProvider())
+#pragma warning restore ASP0000
+{
+    await secretsProvider.GetRequiredService<SqliteSecretsStoreMigrator>().MigrateAsync(default);
+    var resolver = secretsProvider.GetRequiredService<ISecretResolver>();
+    await new SecretReferenceExpander(resolver)
+        .ExpandConfigurationAsync((IConfigurationRoot)builder.Configuration, default);
+}
+
 // Anchor the process working directory to the install directory (AppContext.BaseDirectory) so every
 // relative runtime path resolves under the install dir rather than the service's startup CWD. A Windows
 // service starts with CWD=C:\Windows\System32, which otherwise scattered the Serilog rolling-file sink
@@ -147,6 +176,20 @@ if (hasDriver)
        builder.Configuration,
        (_, sp) => GatewayHistorian.CreateAlarmWriter(serverHistorianOptions, sp));

+    // Node-local LocalDb: caches the deployed-configuration artifact so this node can boot from
+    // its last-known-good config when central SQL is unreachable, and optionally replicates that
+    // cache to its redundant pair peer. Driver-role only — admin-only nodes have nothing to cache,
+    // and registering here would impose LocalDb:Path-required-or-no-boot on them for nothing.
+    // Storage ships unconditionally; replication stays inert until LocalDb:Replication:PeerAddress
+    // (initiator) / LocalDb:SyncListenPort (listener) are set. See LocalDbRegistration.
+    builder.Services.AddOtOpcUaLocalDb(builder.Configuration);
+
+    // gRPC server plumbing for the passive sync endpoint mapped below. Registered only under
+    // hasDriver so admin-only nodes expose no sync surface at all. The interceptor is the ONLY
+    // inbound auth on that endpoint — the replication library's LocalDbSyncService verifies
+    // nothing — and it fail-closes when no ApiKey is configured.
+    builder.Services.AddGrpc(o => o.Interceptors.Add<LocalDbSyncAuthInterceptor>());
+
    // Config-gated server-side HistoryRead backend. When the ServerHistorian section is enabled this
    // overrides the NullHistorianDataSource default from AddOtOpcUaRuntime (last registration wins) with
    // a read-only HistorianGateway-backed data source the node manager's HistoryRead overrides
@@ -287,6 +330,14 @@ if (hasDriver)
 builder.Services.AddAkka("otopcua", (ab, sp) =>
 {
    ab.WithOtOpcUaClusterBootstrap(sp);
+    // Secret-replication wire protocol → its own serializer, merged only when replication is on so a
+    // non-replicating node carries no serializer bindings for messages it will never see. Appended
+    // (Akka.Hosting's fallback merge — the same mode WithOtOpcUaClusterBootstrap uses for the base
+    // config) rather than a raw Config.WithFallback, which would fight the builder's own assembly.
+    // Without this the protocol DTOs would round-trip on Akka's default JSON serializer, leaving the
+    // serializer that carries secret ciphertext an inherited default rather than an explicit choice.
+    if (SecretsRegistration.IsReplicationEnabled(builder.Configuration))
+        ab.AddHocon(AkkaSecretsReplication.SerializationConfig, HoconAddMode.Append);
    if (hasAdmin)
    {
        ab.WithOtOpcUaControlPlaneSingletons();
@@ -323,9 +374,99 @@ if (hasAdmin)
    builder.Services.AddOtOpcUaAdminClients();
 }

+// Registered unconditionally: driver-role nodes resolve Layer-B DriverConfig secrets and have no auth/DP/AdminUI.
+// Cluster replication is opt-in behind Secrets:Replication:Enabled (default false) — see SecretsRegistration.
+builder.Services.AddOtOpcUaSecrets(builder.Configuration);
+
 builder.Services.AddOtOpcUaHealth();
 builder.Services.AddOtOpcUaObservability(builder.Configuration);

+// ---------------------------------------------------------------------------------------------
+// LocalDb sync listener (default-OFF).
+//
+// DANGER: any explicit Kestrel Listen* call makes Kestrel IGNORE ASPNETCORE_URLS/urls ENTIRELY
+// (it logs "Overriding address(es)"). The host has no ConfigureKestrel today and binds solely via
+// that configuration, so adding a listener naively would silently unbind the AdminUI + deploy API
+// behind Traefik. Everything the host was already asked to serve is therefore re-bound explicitly
+// in the same block.
+//
+// The listener is HTTP/2-ONLY on purpose: the sync client speaks prior-knowledge h2c, which a
+// cleartext Http1AndHttp2 endpoint cannot negotiate (there is no ALPN without TLS). Hence a
+// dedicated port rather than multiplexing onto the main one.
+//
+// When LocalDb:SyncListenPort is 0 (the default) none of this runs and URL binding is untouched.
+// ---------------------------------------------------------------------------------------------
+var syncListenPort = LocalDbRegistration.SyncListenPort(builder.Configuration);
+if (hasDriver && syncListenPort > 0)
+{
+    // Mirror Kestrel's own source precedence: URLS wins; else the HTTP_PORTS/HTTPS_PORTS bare-port
+    // vars; else Kestrel's localhost:5000 default. Missing the HTTP_PORTS leg is not academic — the
+    // aspnet:8.0+ base images set ASPNETCORE_HTTP_PORTS=8080 as the CONTAINER default in place of
+    // ASPNETCORE_URLS, so a driver node that never sets URLS is really serving :8080 on all
+    // interfaces. Falling straight through to localhost:5000 would silently move its health/metrics
+    // surface to loopback (found on the docker-dev live gate).
+    var configuredUrls = builder.Configuration["urls"]
+                      ?? builder.Configuration["ASPNETCORE_URLS"];
+    var existingBindings = KestrelHttpBinding.Parse(configuredUrls);
+
+    if (existingBindings.Count == 0)
+    {
+        var httpPorts = builder.Configuration["ASPNETCORE_HTTP_PORTS"] ?? builder.Configuration["HTTP_PORTS"];
+        var httpsPorts = builder.Configuration["ASPNETCORE_HTTPS_PORTS"] ?? builder.Configuration["HTTPS_PORTS"];
+        existingBindings =
+        [
+            .. KestrelHttpBinding.ParsePorts(httpPorts, isSecure: false),
+            .. KestrelHttpBinding.ParsePorts(httpsPorts, isSecure: true),
+        ];
+        if (existingBindings.Count > 0)
+            Log.Information(
+                "LocalDb sync listener enabled; re-binding the HTTP_PORTS surface ({HttpPorts}/{HttpsPorts}) " +
+                "alongside the sync port.", httpPorts, httpsPorts);
+    }
+
+    // A driver-only Windows-service node gets NO URLS and NO *_PORTS (Install-Services.ps1 sets URLS
+    // only under $hasAdmin), so "nothing configured" is a real, supported state — not an error.
+    // Kestrel's own default is localhost:5000; re-state it explicitly, because taking over
+    // configuration means taking over the default too. Health probes hit this port.
+    if (existingBindings.Count == 0)
+    {
+        existingBindings = [new KestrelHttpBinding("localhost", 5000, IsSecure: false)];
+        Log.Information(
+            "LocalDb sync listener enabled with no URLs configured; re-binding Kestrel's default " +
+            "http://localhost:5000 alongside the sync port.");
+    }
+
+    // Re-binding an https endpoint would need its certificate configuration replayed too, which
+    // this host does not model (TLS is terminated at Traefik). Rather than silently serve it
+    // without TLS — or drop it — refuse to take over Kestrel at all and leave the existing
+    // surface exactly as it was. The operator gets a loud, actionable error instead of an
+    // AdminUI that stopped answering.
+    if (existingBindings.Any(b => b.IsSecure))
+    {
+        Log.Error(
+            "LocalDb:SyncListenPort is set to {Port} but this host serves HTTPS endpoint(s) ({Urls}). " +
+            "Binding the sync listener requires re-binding every existing endpoint explicitly, and the " +
+            "HTTPS certificate configuration cannot be replayed safely. The sync listener is DISABLED; " +
+            "terminate TLS upstream (as the docker-dev rig does) or leave replication off on this node.",
+            syncListenPort, configuredUrls);
+        syncListenPort = 0;
+    }
+    else
+    {
+        builder.WebHost.ConfigureKestrel(kestrel =>
+        {
+            foreach (var binding in existingBindings)
+                binding.Apply(kestrel);
+
+            kestrel.ListenAnyIP(syncListenPort, o => o.Protocols = HttpProtocols.Http2);
+        });
+
+        Log.Information(
+            "LocalDb sync listener bound on :{SyncPort} (h2c); re-bound existing endpoint(s) {Urls}.",
+            syncListenPort, configuredUrls ?? "http://localhost:5000 (Kestrel default)");
+    }
+}
+
 var app = builder.Build();

 // AddZbSerilog registers Serilog as the MEL logging provider but does NOT assign the static
@@ -356,6 +497,15 @@ if (hasAdmin)
    app.MapOtOpcUaDeployApi(app.Configuration);
 }

+// Passive LocalDb sync endpoint. Gated on the same port check that bound the listener, so a
+// default-OFF or admin-only graph carries no sync surface whatsoever. Mapping it would be safe
+// even unauthenticated — LocalDbSyncAuthInterceptor fail-closes with no ApiKey configured — but
+// not mapping it at all is the stronger default.
+if (hasDriver && syncListenPort > 0)
+{
+    app.MapZbLocalDbSync();
+}
+
 app.MapOtOpcUaHealth();
 app.MapOtOpcUaMetrics();

--- a/Show More
+++ b/Show More