docs: backfill XML documentation across 756 files

Adds <summary>, <param>, <typeparam>, and <inheritdoc/> tags to public
members surfaced by commentchecker — resolves 5,847 of 5,869 issues
(99.6%) across three /fixdocs passes.

.github/workflows/v2-ci.yml

@@ -61,10 +61,16 @@ jobs:
   integration:
     needs: build
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        project:
+          - tests/Server/ZB.MOM.WW.OtOpcUa.Host.IntegrationTests
+          - tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.IntegrationTests
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-dotnet@v4
         with:
           dotnet-version: 10.0.x
-      - name: dotnet test Host.IntegrationTests
-        run: dotnet test tests/Server/ZB.MOM.WW.OtOpcUa.Host.IntegrationTests --configuration Release --filter "Category!=E2E"
+      - name: dotnet test ${{ matrix.project }}
+        run: dotnet test ${{ matrix.project }} --configuration Release --filter "Category!=E2E"

ZB.MOM.WW.OtOpcUa.slnx

@@ -63,6 +63,7 @@
   <Folder Name="/tests/Server/">
     <Project Path="tests/Server/ZB.MOM.WW.OtOpcUa.ControlPlane.Tests/ZB.MOM.WW.OtOpcUa.ControlPlane.Tests.csproj" />
     <Project Path="tests/Server/ZB.MOM.WW.OtOpcUa.Host.IntegrationTests/ZB.MOM.WW.OtOpcUa.Host.IntegrationTests.csproj" />
+    <Project Path="tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.IntegrationTests/ZB.MOM.WW.OtOpcUa.OpcUaServer.IntegrationTests.csproj" />
     <Project Path="tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.Tests/ZB.MOM.WW.OtOpcUa.OpcUaServer.Tests.csproj" />
     <Project Path="tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests/ZB.MOM.WW.OtOpcUa.Runtime.Tests.csproj" />
     <Project Path="tests/Server/ZB.MOM.WW.OtOpcUa.Security.Tests/ZB.MOM.WW.OtOpcUa.Security.Tests.csproj" />

docker-dev/README.md

@@ -1,20 +1,70 @@
 # docker-dev
 
-Mac-friendly four-node OtOpcUa fleet for manual UI exercise + integration smoke tests. Spins up an Akka cluster + SQL Server + OpenLDAP + Traefik in front of two admin nodes.
+Mac-friendly multi-cluster OtOpcUa fleet for manual UI exercise + integration smoke tests. Spins up **three isolated Akka clusters** + SQL Server + OpenLDAP + Traefik on the same Compose network. All three clusters share the single `OtOpcUa` ConfigDb — multi-tenancy is enforced by per-row `ServerCluster.ClusterId` scoping. Akka.Cluster gossip stays isolated between meshes because their seed-node lists are disjoint, even though they share the same system name `otopcua`.
 
 ## Stack
 
+### Shared infrastructure
+
 | Service | Role | Ports |
 |---|---|---|
-| `sql` | SQL Server 2022 (`ConfigDb` backing store) | host `14330` → container `1433` |
-| `ldap` | OpenLDAP with dev users `alice` / `bob` | host `3893` → container `1389` |
-| `admin-a` | OtOpcUa.Host, `OTOPCUA_ROLES=admin`, cluster seed | internal `9000` |
-| `admin-b` | OtOpcUa.Host, `OTOPCUA_ROLES=admin`, joins admin-a | internal `9000` |
-| `driver-a` | OtOpcUa.Host, `OTOPCUA_ROLES=driver` | host `4840` → container `4840` |
-| `driver-b` | OtOpcUa.Host, `OTOPCUA_ROLES=driver` | host `4841` → container `4840` |
-| `traefik` | Routes `:80` to whichever admin-* currently passes `/health/active` | host `80`, dashboard `8080` |
+| `sql` | SQL Server 2022 — single `OtOpcUa` ConfigDb shared by all three clusters | host `14330` → container `1433` |
+| `traefik` | Routes :80 by Host header / PathPrefix | host `80`, dashboard `8089` |
 
-All six containers share an Akka cluster bound to port `4053` inside the Compose network. The Akka `PublicHostname` of each container matches its Compose service name; the seed-node list points at `admin-a` so the other three join via that.
+Authentication runs in `DevStubMode` — every host container has `Authentication__Ldap__DevStubMode=true` set, so the LDAP service is not part of the dev compose right now (the `bitnami/openldap:2.6` image was retired and the legacy tag crashes mid-setup with exit 68). Any non-empty username/password signs in as `FleetAdmin`. To restore a real LDAP service, drop the env var and add an `openldap`-compatible image back to compose.
+
+### Main cluster — split admin/driver roles
+
+| Service | Role | Ports |
+|---|---|---|
+| `admin-a` | `OTOPCUA_ROLES=admin`, cluster seed | internal `9000` |
+| `admin-b` | `OTOPCUA_ROLES=admin`, joins admin-a | internal `9000` |
+| `driver-a` | `OTOPCUA_ROLES=driver` | host `4840` → container `4840` |
+| `driver-b` | `OTOPCUA_ROLES=driver` | host `4841` → container `4840` |
+
+### Site A cluster — 2-node fused admin+driver
+
+| Service | Role | Ports |
+|---|---|---|
+| `site-a-1` | `OTOPCUA_ROLES=admin,driver`, cluster seed | host `4842` → container `4840` |
+| `site-a-2` | `OTOPCUA_ROLES=admin,driver`, joins site-a-1 | host `4843` → container `4840` |
+
+### Site B cluster — 2-node fused admin+driver
+
+| Service | Role | Ports |
+|---|---|---|
+| `site-b-1` | `OTOPCUA_ROLES=admin,driver`, cluster seed | host `4844` → container `4840` |
+| `site-b-2` | `OTOPCUA_ROLES=admin,driver`, joins site-b-1 | host `4845` → container `4840` |
+
+All containers bind Akka remoting to port `4053` inside their own network namespace; the `PublicHostname` of each matches its Compose service name. Akka mesh isolation is enforced purely by disjoint seed lists. Configuration-side isolation is enforced by `ServerCluster.ClusterId` — see "Multi-tenancy" below.
+
+## Multi-tenancy
+
+All eight host nodes write to the same `OtOpcUa` ConfigDb. The `ServerCluster` table differentiates the three Akka meshes: each Akka cluster maps to one row, and each `ClusterNode` row's `ClusterId` ties the runtime node back to its owning cluster scope.
+
+A one-shot `cluster-seed` Compose service (image `mcr.microsoft.com/mssql-tools`) waits for SQL + the EF auto-migration to complete and then INSERTs the rows below. The seed is **idempotent** — `IF NOT EXISTS` guards every insert — so re-runs on `docker compose up` are no-ops:
+
+| Akka mesh | `ServerCluster.ClusterId` | `ClusterNode.NodeId` rows |
+|---|---|---|
+| Main | `MAIN` | `driver-a`, `driver-b` (OPC UA publishers) |
+| Site A | `SITE-A` | `site-a-1`, `site-a-2` |
+| Site B | `SITE-B` | `site-b-1`, `site-b-2` |
+
+`ClusterNode` is the table for **OPC UA-publishing nodes** (not every Akka cluster member), which is why the main cluster's `admin-a` / `admin-b` don't get rows — they're control-plane-only.
+
+Each `ClusterNode.NodeId` matches the node's `Cluster__PublicHostname` env value (Compose service name) — that's the lookup the runtime uses to resolve its own membership. `ApplicationUri` follows the `urn:OtOpcUa:<NodeId>` convention.
+
+The SQL lives at `seed/seed-clusters.sql`; the wait-and-apply wrapper lives at `seed/entrypoint.sh`. To re-seed manually:
+
+```bash
+docker compose -f docker-dev/docker-compose.yml run --rm cluster-seed
+```
+
+### Galaxy / MxAccess gateway
+
+The seed also pre-creates a `SystemPlatform` Namespace + a `GalaxyMxGateway` DriverInstance in the MAIN cluster pointing at `http://10.100.0.48:5120`. The API key is resolved from the `GALAXY_MXGW_API_KEY` env var set on every driver-role container in compose; override via `GALAXY_MXGW_API_KEY=... docker compose up -d` to swap keys without editing the compose file.
+
+The DriverHost actor doesn't spawn drivers from raw DriverInstance rows on its own — the v2 deploy lifecycle requires a *sealed Deployment* before drivers materialise. After first bring-up, sign in to the Admin UI and click **Deploy current configuration** on `/deployments` to compose the seeded rows into an artifact and dispatch it. The Galaxy driver instance will start its gRPC connection to the gateway on the next deploy ack.
 
 ## Bring up
 
@@ -22,24 +72,21 @@ All six containers share an Akka cluster bound to port `4053` inside the Compose
 # from the repo root
 docker compose -f docker-dev/docker-compose.yml up -d --build
 
-# wait ~15 seconds for SQL to come up + the cluster to form
+# wait ~20 seconds for SQL to come up + all three clusters to form
 
-open http://localhost          # Blazor admin UI via Traefik
-open http://localhost:8080     # Traefik dashboard
+open http://localhost                      # main cluster admin UI
+open http://site-a.localhost               # site A admin UI
+open http://site-b.localhost               # site B admin UI
+open http://localhost:8089                 # Traefik dashboard
 ```
 
+On macOS, `*.localhost` resolves to `127.0.0.1` automatically. On Linux add `127.0.0.1 site-a.localhost site-b.localhost` to `/etc/hosts` if your resolver doesn't.
+
 The first build takes a few minutes (.NET SDK image + restore + publish). Subsequent rebuilds are faster with Docker's layer cache.
 
 ## Auth (dev only)
 
-Use one of the LDAP dev users from `LDAP_USERS` in `docker-compose.yml`:
-
-| Username | Password |
-|---|---|
-| `alice` | `alice123` |
-| `bob` | `bob123` |
-
-The compose mounts everyone into `ou=FleetAdmin` so the dev role mapping resolves to `FleetAdmin`.
+`Authentication__Ldap__DevStubMode=true` is set on every host container, so any non-empty username/password signs in as a `FleetAdmin` user without contacting an LDAP server. **Do not** ship this configuration to production — set `DevStubMode=false` and wire a real LDAP backend before any non-dev deployment.
 
 ## Tear down
 
@@ -51,12 +98,15 @@ The `-v` drops the SQL + LDAP volumes; remove it to keep ConfigDb state across r
 
 ## Failover smoke
 
-1. Watch the Traefik dashboard at `http://localhost:8080`. Both `admin-a` and `admin-b` should be listed as healthy in the `otopcua-admin` service.
+1. Watch the Traefik dashboard at `http://localhost:8089`. Both `admin-a` and `admin-b` should be listed as healthy in the `otopcua-admin` service.
 2. `docker compose -f docker-dev/docker-compose.yml stop admin-a` — `admin-b` should pick up the admin role-leader within ~15 s (Akka split-brain stable-after). Traefik will route traffic to `admin-b` once its `/health/active` returns 200.
 3. `docker compose -f docker-dev/docker-compose.yml start admin-a` — `admin-a` rejoins as a follower; `admin-b` keeps the leader role until something disturbs it.
 
 ## Notes
 
 - This compose is for the **local Mac/Linux developer rig**. The team's CI + soak runs go to the remote docker host at `10.100.0.35` (see `docs/v2/dev-environment.md`); the file there mirrors this one with adjusted port bindings.
-- The OPC UA driver endpoints (`opc.tcp://localhost:4840`, `opc.tcp://localhost:4841`) are reachable directly from the host — Traefik is only in front of the admin HTTP surface.
+- The OPC UA driver endpoints are reachable directly from the host (Traefik is only in front of the admin HTTP surface):
+  - Main: `opc.tcp://localhost:4840` (driver-a), `opc.tcp://localhost:4841` (driver-b)
+  - Site A: `opc.tcp://localhost:4842` (site-a-1), `opc.tcp://localhost:4843` (site-a-2)
+  - Site B: `opc.tcp://localhost:4844` (site-b-1), `opc.tcp://localhost:4845` (site-b-2)
 - Galaxy + Wonderware drivers can't run in Linux containers (they need the Windows-only mxaccessgw + Historian SDK). On non-Windows, `DriverInstanceActor.ShouldStub(driverType, roles)` returns `true` for those types and the actor goes straight to a `Stubbed` state that returns deterministic success.

docker-dev/docker-compose.yml

@@ -1,18 +1,41 @@
-# docker-dev/ — Mac-friendly four-node fleet for v2 development + manual UI exercise.
+# docker-dev/ — Mac-friendly multi-cluster fleet for v2 development + manual UI exercise.
 #
-# Stack:
-#   sql       SQL Server 2022 (ConfigDb backing store)
-#   ldap      OpenLDAP with the dev users from C:\publish\glauth\auth.md mirrored in
-#   admin-a   OtOpcUa.Host with OTOPCUA_ROLES=admin (cluster seed)
-#   admin-b   OtOpcUa.Host with OTOPCUA_ROLES=admin (joins admin-a)
-#   driver-a  OtOpcUa.Host with OTOPCUA_ROLES=driver (joins via admin-a)
-#   driver-b  OtOpcUa.Host with OTOPCUA_ROLES=driver (joins via admin-a)
-#   traefik   Routes :80 to whichever admin-* currently passes /health/active
+# Stack (3 separate Akka clusters — all share the single `OtOpcUa` ConfigDb):
+#   sql        SQL Server 2022 — hosts the one ConfigDb that all three clusters use
+#   ldap       OpenLDAP with the dev users from C:\publish\glauth\auth.md mirrored in
+#
+#   Main cluster (existing — split-role admin / driver pair on a single Akka mesh):
+#     admin-a   OtOpcUa.Host with OTOPCUA_ROLES=admin (seed)
+#     admin-b   OtOpcUa.Host with OTOPCUA_ROLES=admin (joins admin-a)
+#     driver-a  OtOpcUa.Host with OTOPCUA_ROLES=driver (joins via admin-a)
+#     driver-b  OtOpcUa.Host with OTOPCUA_ROLES=driver (joins via admin-a)
+#
+#   Site A cluster (2-node fused admin+driver):
+#     site-a-1, site-a-2     OTOPCUA_ROLES=admin,driver, seed = site-a-1
+#
+#   Site B cluster (2-node fused admin+driver):
+#     site-b-1, site-b-2     OTOPCUA_ROLES=admin,driver, seed = site-b-1
+#
+#   traefik    PathPrefix → main cluster admin-a/admin-b; Host(`site-a.localhost`) →
+#              site-a-*; Host(`site-b.localhost`) → site-b-*. Add the two site hosts to
+#              your /etc/hosts (or rely on macOS `.localhost` auto-resolution).
+#
+# Multi-tenancy: ConfigDb is one schema with a `ServerCluster` table; each Akka cluster
+# corresponds to a row in it (ClusterId = "MAIN" / "SITE-A" / "SITE-B"), and each node's
+# `ClusterNode.NodeId` points back at the row that owns it. After first boot, sign in to
+# any cluster's Admin UI and create the matching ServerCluster + ClusterNode rows via
+# /clusters and /hosts so the runtime knows what configuration scope applies.
+#
+# Akka mesh isolation: same system name "otopcua" + same remoting port 4053 inside each
+# container's own network namespace, but with disjoint seed-node lists — gossip never
+# crosses between the three meshes.
 #
 # Usage:
 #   docker compose -f docker-dev/docker-compose.yml up -d --build
-#   open http://localhost            # Blazor admin UI via Traefik
-#   open http://localhost:8080       # Traefik dashboard
+#   open http://localhost                  # main cluster Blazor admin UI
+#   open http://site-a.localhost           # site A admin UI
+#   open http://site-b.localhost           # site B admin UI
+#   open http://localhost:8089             # Traefik dashboard (8080 is the sister scadalink stack)
 #
 # Tear-down:  docker compose -f docker-dev/docker-compose.yml down -v
 
@@ -34,17 +57,26 @@ services:
       timeout: 5s
       retries: 20
 
-  ldap:
-    image: bitnami/openldap:2.6
-    environment:
-      LDAP_ROOT: "dc=lmxopcua,dc=local"
-      LDAP_ADMIN_USERNAME: "admin"
-      LDAP_ADMIN_PASSWORD: "ldapadmin"
-      LDAP_USERS: "alice,bob"
-      LDAP_PASSWORDS: "alice123,bob123"
-      LDAP_USER_DC: "ou=FleetAdmin"
-    ports:
-      - "3893:1389"
+  # ── Cluster seed (one-shot) ────────────────────────────────────────────────
+  # Waits for SQL + the host containers' EF auto-migration, then INSERTs the
+  # three ServerCluster rows and the six ClusterNode rows that scope each Akka
+  # mesh inside the shared OtOpcUa ConfigDb. Idempotent — re-runs are no-ops.
+  cluster-seed:
+    image: mcr.microsoft.com/mssql-tools:latest
+    depends_on:
+      sql:
+        condition: service_healthy
+    volumes:
+      - ./seed:/seed:ro
+    entrypoint: ["/bin/bash", "/seed/entrypoint.sh"]
+    restart: "no"
+
+  # OpenLDAP was previously here but the bitnami/openldap:2.6 image was retired
+  # (manifest gone) and bitnamilegacy/openldap:2.6 crashes during LDIF setup with
+  # exit 68. For the dev compose every host container now runs with
+  # Authentication__Ldap__DevStubMode=true, so any non-empty username/password
+  # signs in as `FleetAdmin`. Restore a real LDAP service when there's a need
+  # for end-to-end LDAP coverage (the host code path is unchanged).
 
   admin-a: &otopcua-host
     build:
@@ -65,9 +97,8 @@ services:
       Security__Jwt__SigningKey: "docker-dev-signing-key-with-at-least-32-bytes-of-utf8-content-12345"
       Security__Jwt__Issuer: "otopcua-dev"
       Security__Jwt__Audience: "otopcua-dev"
-      Authentication__Ldap__Server: "ldap"
-      Authentication__Ldap__Port: "1389"
-      Authentication__Ldap__AllowInsecureLdap: "true"
+      Authentication__Ldap__DevStubMode: "true"
+      GALAXY_MXGW_API_KEY: "${GALAXY_MXGW_API_KEY:-mxgw_otopcua__UY_NKlBl3vWuZt8HD7usfZsU76eibMKB6CufwzabUI}"
 
   admin-b:
     <<: *otopcua-host
@@ -83,9 +114,8 @@ services:
       Security__Jwt__SigningKey: "docker-dev-signing-key-with-at-least-32-bytes-of-utf8-content-12345"
       Security__Jwt__Issuer: "otopcua-dev"
       Security__Jwt__Audience: "otopcua-dev"
-      Authentication__Ldap__Server: "ldap"
-      Authentication__Ldap__Port: "1389"
-      Authentication__Ldap__AllowInsecureLdap: "true"
+      Authentication__Ldap__DevStubMode: "true"
+      GALAXY_MXGW_API_KEY: "${GALAXY_MXGW_API_KEY:-mxgw_otopcua__UY_NKlBl3vWuZt8HD7usfZsU76eibMKB6CufwzabUI}"
 
   driver-a:
     <<: *otopcua-host
@@ -97,6 +127,9 @@ services:
       Cluster__PublicHostname: "driver-a"
       Cluster__SeedNodes__0: "akka.tcp://otopcua@admin-a:4053"
       Cluster__Roles__0: "driver"
+      # 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_otopcua__UY_NKlBl3vWuZt8HD7usfZsU76eibMKB6CufwzabUI}"
     ports:
       - "4840:4840"
 
@@ -110,9 +143,103 @@ services:
       Cluster__PublicHostname: "driver-b"
       Cluster__SeedNodes__0: "akka.tcp://otopcua@admin-a:4053"
       Cluster__Roles__0: "driver"
+      GALAXY_MXGW_API_KEY: "${GALAXY_MXGW_API_KEY:-mxgw_otopcua__UY_NKlBl3vWuZt8HD7usfZsU76eibMKB6CufwzabUI}"
     ports:
       - "4841:4840"
 
+  # ── Site A cluster (2-node fused admin+driver) ──────────────────────────────
+  # Shares the OtOpcUa ConfigDb with the main + site-b clusters; multi-tenancy is
+  # enforced by ServerCluster.ClusterId rows (configure via /clusters after boot).
+  # Akka isolation comes from the disjoint seed list (seed = site-a-1).
+
+  site-a-1:
+    <<: *otopcua-host
+    environment:
+      OTOPCUA_ROLES: "admin,driver"
+      ASPNETCORE_URLS: "http://+:9000"
+      ConnectionStrings__ConfigDb: "Server=sql,1433;Database=OtOpcUa;User Id=sa;Password=OtOpcUa!Dev123;TrustServerCertificate=True;"
+      Cluster__Hostname: "0.0.0.0"
+      Cluster__Port: "4053"
+      Cluster__PublicHostname: "site-a-1"
+      Cluster__SeedNodes__0: "akka.tcp://otopcua@site-a-1:4053"
+      Cluster__Roles__0: "admin"
+      Cluster__Roles__1: "driver"
+      Security__Jwt__SigningKey: "docker-dev-signing-key-with-at-least-32-bytes-of-utf8-content-12345"
+      Security__Jwt__Issuer: "otopcua-dev"
+      Security__Jwt__Audience: "otopcua-dev"
+      Authentication__Ldap__DevStubMode: "true"
+      GALAXY_MXGW_API_KEY: "${GALAXY_MXGW_API_KEY:-mxgw_otopcua__UY_NKlBl3vWuZt8HD7usfZsU76eibMKB6CufwzabUI}"
+    ports:
+      - "4842:4840"
+
+  site-a-2:
+    <<: *otopcua-host
+    depends_on:
+      sql: { condition: service_healthy }
+      site-a-1: { condition: service_started }
+    environment:
+      OTOPCUA_ROLES: "admin,driver"
+      ASPNETCORE_URLS: "http://+:9000"
+      ConnectionStrings__ConfigDb: "Server=sql,1433;Database=OtOpcUa;User Id=sa;Password=OtOpcUa!Dev123;TrustServerCertificate=True;"
+      Cluster__Hostname: "0.0.0.0"
+      Cluster__Port: "4053"
+      Cluster__PublicHostname: "site-a-2"
+      Cluster__SeedNodes__0: "akka.tcp://otopcua@site-a-1:4053"
+      Cluster__Roles__0: "admin"
+      Cluster__Roles__1: "driver"
+      Security__Jwt__SigningKey: "docker-dev-signing-key-with-at-least-32-bytes-of-utf8-content-12345"
+      Security__Jwt__Issuer: "otopcua-dev"
+      Security__Jwt__Audience: "otopcua-dev"
+      Authentication__Ldap__DevStubMode: "true"
+      GALAXY_MXGW_API_KEY: "${GALAXY_MXGW_API_KEY:-mxgw_otopcua__UY_NKlBl3vWuZt8HD7usfZsU76eibMKB6CufwzabUI}"
+    ports:
+      - "4843:4840"
+
+  # ── Site B cluster (2-node fused admin+driver) ──────────────────────────────
+
+  site-b-1:
+    <<: *otopcua-host
+    environment:
+      OTOPCUA_ROLES: "admin,driver"
+      ASPNETCORE_URLS: "http://+:9000"
+      ConnectionStrings__ConfigDb: "Server=sql,1433;Database=OtOpcUa;User Id=sa;Password=OtOpcUa!Dev123;TrustServerCertificate=True;"
+      Cluster__Hostname: "0.0.0.0"
+      Cluster__Port: "4053"
+      Cluster__PublicHostname: "site-b-1"
+      Cluster__SeedNodes__0: "akka.tcp://otopcua@site-b-1:4053"
+      Cluster__Roles__0: "admin"
+      Cluster__Roles__1: "driver"
+      Security__Jwt__SigningKey: "docker-dev-signing-key-with-at-least-32-bytes-of-utf8-content-12345"
+      Security__Jwt__Issuer: "otopcua-dev"
+      Security__Jwt__Audience: "otopcua-dev"
+      Authentication__Ldap__DevStubMode: "true"
+      GALAXY_MXGW_API_KEY: "${GALAXY_MXGW_API_KEY:-mxgw_otopcua__UY_NKlBl3vWuZt8HD7usfZsU76eibMKB6CufwzabUI}"
+    ports:
+      - "4844:4840"
+
+  site-b-2:
+    <<: *otopcua-host
+    depends_on:
+      sql: { condition: service_healthy }
+      site-b-1: { condition: service_started }
+    environment:
+      OTOPCUA_ROLES: "admin,driver"
+      ASPNETCORE_URLS: "http://+:9000"
+      ConnectionStrings__ConfigDb: "Server=sql,1433;Database=OtOpcUa;User Id=sa;Password=OtOpcUa!Dev123;TrustServerCertificate=True;"
+      Cluster__Hostname: "0.0.0.0"
+      Cluster__Port: "4053"
+      Cluster__PublicHostname: "site-b-2"
+      Cluster__SeedNodes__0: "akka.tcp://otopcua@site-b-1:4053"
+      Cluster__Roles__0: "admin"
+      Cluster__Roles__1: "driver"
+      Security__Jwt__SigningKey: "docker-dev-signing-key-with-at-least-32-bytes-of-utf8-content-12345"
+      Security__Jwt__Issuer: "otopcua-dev"
+      Security__Jwt__Audience: "otopcua-dev"
+      Authentication__Ldap__DevStubMode: "true"
+      GALAXY_MXGW_API_KEY: "${GALAXY_MXGW_API_KEY:-mxgw_otopcua__UY_NKlBl3vWuZt8HD7usfZsU76eibMKB6CufwzabUI}"
+    ports:
+      - "4845:4840"
+
   traefik:
     image: traefik:v3.1
     command:
@@ -122,9 +249,13 @@ services:
       - --api.insecure=true
     ports:
       - "80:80"
-      - "8080:8080"
+      - "8089:8080"  # 8080 conflicts with the sister scadalink dev stack
     volumes:
       - ./traefik-dynamic.yml:/etc/traefik/dynamic.yml:ro
     depends_on:
       - admin-a
       - admin-b
+      - site-a-1
+      - site-a-2
+      - site-b-1
+      - site-b-2

docker-dev/seed/entrypoint.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# docker-dev cluster-seed entrypoint. Waits for the OtOpcUa ConfigDb schema to
+# be in place, then applies the idempotent row seed.
+#
+# IMPORTANT: this container does NOT run EF migrations — sqlcmd can't execute
+# the V2 migration script cleanly because it contains CREATE PROCEDURE
+# statements inside IF NOT EXISTS BEGIN ... END blocks (procs must be the
+# first statement in their batch). Migrations are owned by the operator:
+#
+#     dotnet ef database update \
+#         --project src/Core/ZB.MOM.WW.OtOpcUa.Configuration \
+#         --startup-project src/Server/ZB.MOM.WW.OtOpcUa.Host
+#
+# (with ConnectionStrings__ConfigDb pointing at Server=localhost,14330;...).
+# Once the schema is in place, restart the cluster-seed container — or just
+# `docker compose up -d` and the seed will pick up where it left off thanks to
+# the IF NOT EXISTS guards in seed-clusters.sql.
+
+set -euo pipefail
+
+SQLCMD="/opt/mssql-tools/bin/sqlcmd"
+SERVER="${SQL_HOST:-sql},1433"
+USER="${SQL_USER:-sa}"
+PASS="${SQL_PASSWORD:-OtOpcUa!Dev123}"
+DB="${SQL_DATABASE:-OtOpcUa}"
+
+run_sql_in() {
+    local target_db="$1"; shift
+    # -I forces SET QUOTED_IDENTIFIER ON (needed for filtered indexes if you
+    # ever extend this script to touch them).
+    "$SQLCMD" -S "$SERVER" -U "$USER" -P "$PASS" -d "$target_db" -b -h -1 -I "$@"
+}
+
+echo "[cluster-seed] waiting for SQL Server to accept connections..."
+until run_sql_in master -Q "SELECT 1" >/dev/null 2>&1; do
+    sleep 2
+done
+echo "[cluster-seed] SQL Server up."
+
+echo "[cluster-seed] waiting for ${DB} database + dbo.ServerCluster table (operator must run dotnet ef database update)..."
+until run_sql_in "$DB" -Q "IF OBJECT_ID('dbo.ServerCluster') IS NULL THROW 50001, 'missing', 1; SELECT 1" >/dev/null 2>&1; do
+    sleep 3
+done
+echo "[cluster-seed] schema ready."
+
+echo "[cluster-seed] applying seed-clusters.sql (ServerCluster + ClusterNode rows)..."
+run_sql_in "$DB" -i /seed/seed-clusters.sql
+echo "[cluster-seed] done."

docker-dev/seed/seed-clusters.sql

@@ -0,0 +1,195 @@
+-- docker-dev cluster seed. Idempotent — safe to re-run on every `docker compose up`.
+--
+-- Populates:
+--   ServerCluster   MAIN, SITE-A, SITE-B
+--   ClusterNode     driver-a, driver-b  → MAIN
+--                   site-a-1, site-a-2  → SITE-A
+--                   site-b-1, site-b-2  → SITE-B
+--
+-- ServerCluster.NodeCount + RedundancyMode are coupled by CHECK constraint:
+--   NodeCount=1 ⇒ RedundancyMode='None'
+--   NodeCount=2 ⇒ RedundancyMode∈('Warm','Hot')
+--
+-- Each ClusterNode.ApplicationUri MUST be globally unique (UX_ClusterNode_ApplicationUri).
+-- Convention: urn:OtOpcUa:<NodeId>.
+--
+-- Host = Compose service name (resolves inside the otopcua-dev network).
+-- OpcUaPort stays at the container-internal 4840; the host-side port mapping is in
+-- docker-compose.yml ports: blocks and is irrelevant to ClusterNode rows.
+
+SET NOCOUNT ON;
+SET XACT_ABORT ON;
+
+BEGIN TRANSACTION;
+
+------------------------------------------------------------------------------
+-- ServerCluster
+------------------------------------------------------------------------------
+
+IF NOT EXISTS (SELECT 1 FROM dbo.ServerCluster WHERE ClusterId = 'MAIN')
+    INSERT INTO dbo.ServerCluster
+        (ClusterId, Name, Enterprise, Site, NodeCount, RedundancyMode, Enabled, Notes, CreatedBy)
+    VALUES
+        ('MAIN', 'Main cluster', 'zb', 'docker-dev',
+         2, 'Warm', 1,
+         'docker-dev seed — admin-a/admin-b control-plane, driver-a/driver-b OPC UA publishers.',
+         'docker-dev-seed');
+
+IF NOT EXISTS (SELECT 1 FROM dbo.ServerCluster WHERE ClusterId = 'SITE-A')
+    INSERT INTO dbo.ServerCluster
+        (ClusterId, Name, Enterprise, Site, NodeCount, RedundancyMode, Enabled, Notes, CreatedBy)
+    VALUES
+        ('SITE-A', 'Site A', 'zb', 'site-a',
+         2, 'Warm', 1,
+         'docker-dev seed — 2-node fused admin+driver cluster.',
+         'docker-dev-seed');
+
+IF NOT EXISTS (SELECT 1 FROM dbo.ServerCluster WHERE ClusterId = 'SITE-B')
+    INSERT INTO dbo.ServerCluster
+        (ClusterId, Name, Enterprise, Site, NodeCount, RedundancyMode, Enabled, Notes, CreatedBy)
+    VALUES
+        ('SITE-B', 'Site B', 'zb', 'site-b',
+         2, 'Warm', 1,
+         'docker-dev seed — 2-node fused admin+driver cluster.',
+         'docker-dev-seed');
+
+------------------------------------------------------------------------------
+-- ClusterNode — main cluster OPC UA publishers
+--
+-- NodeId is "<compose-service>:4053" so it matches what ClusterRoleInfo +
+-- ConfigPublishCoordinator derive from Akka.Cluster.Get(system).State.Members
+-- (member.Address.Host:Port). NodeDeploymentState.NodeId is FK-bound to
+-- ClusterNode.NodeId; mismatched values cause FK 547 on deploy.
+------------------------------------------------------------------------------
+
+IF NOT EXISTS (SELECT 1 FROM dbo.ClusterNode WHERE NodeId = 'driver-a:4053')
+    INSERT INTO dbo.ClusterNode
+        (NodeId, ClusterId, Host, OpcUaPort, DashboardPort, ApplicationUri, ServiceLevelBase, Enabled, CreatedBy)
+    VALUES ('driver-a:4053', 'MAIN', 'driver-a', 4840, 8081, 'urn:OtOpcUa:driver-a', 200, 1, 'docker-dev-seed');
+
+IF NOT EXISTS (SELECT 1 FROM dbo.ClusterNode WHERE NodeId = 'driver-b:4053')
+    INSERT INTO dbo.ClusterNode
+        (NodeId, ClusterId, Host, OpcUaPort, DashboardPort, ApplicationUri, ServiceLevelBase, Enabled, CreatedBy)
+    VALUES ('driver-b:4053', 'MAIN', 'driver-b', 4840, 8081, 'urn:OtOpcUa:driver-b', 150, 1, 'docker-dev-seed');
+
+------------------------------------------------------------------------------
+-- ClusterNode — site A
+------------------------------------------------------------------------------
+
+IF NOT EXISTS (SELECT 1 FROM dbo.ClusterNode WHERE NodeId = 'site-a-1:4053')
+    INSERT INTO dbo.ClusterNode
+        (NodeId, ClusterId, Host, OpcUaPort, DashboardPort, ApplicationUri, ServiceLevelBase, Enabled, CreatedBy)
+    VALUES ('site-a-1:4053', 'SITE-A', 'site-a-1', 4840, 8081, 'urn:OtOpcUa:site-a-1', 200, 1, 'docker-dev-seed');
+
+IF NOT EXISTS (SELECT 1 FROM dbo.ClusterNode WHERE NodeId = 'site-a-2:4053')
+    INSERT INTO dbo.ClusterNode
+        (NodeId, ClusterId, Host, OpcUaPort, DashboardPort, ApplicationUri, ServiceLevelBase, Enabled, CreatedBy)
+    VALUES ('site-a-2:4053', 'SITE-A', 'site-a-2', 4840, 8081, 'urn:OtOpcUa:site-a-2', 150, 1, 'docker-dev-seed');
+
+------------------------------------------------------------------------------
+-- ClusterNode — site B
+------------------------------------------------------------------------------
+
+IF NOT EXISTS (SELECT 1 FROM dbo.ClusterNode WHERE NodeId = 'site-b-1:4053')
+    INSERT INTO dbo.ClusterNode
+        (NodeId, ClusterId, Host, OpcUaPort, DashboardPort, ApplicationUri, ServiceLevelBase, Enabled, CreatedBy)
+    VALUES ('site-b-1:4053', 'SITE-B', 'site-b-1', 4840, 8081, 'urn:OtOpcUa:site-b-1', 200, 1, 'docker-dev-seed');
+
+IF NOT EXISTS (SELECT 1 FROM dbo.ClusterNode WHERE NodeId = 'site-b-2:4053')
+    INSERT INTO dbo.ClusterNode
+        (NodeId, ClusterId, Host, OpcUaPort, DashboardPort, ApplicationUri, ServiceLevelBase, Enabled, CreatedBy)
+    VALUES ('site-b-2:4053', 'SITE-B', 'site-b-2', 4840, 8081, 'urn:OtOpcUa:site-b-2', 150, 1, 'docker-dev-seed');
+
+------------------------------------------------------------------------------
+-- Galaxy MxAccess gateway — MAIN cluster
+--
+-- Namespace.Kind=SystemPlatform is required for Galaxy/MXAccess data per
+-- decision #107; raw equipment drivers use Equipment. DriverInstance points
+-- at the external mxaccessgw process. The driver code lives in this repo
+-- (.NET 10, cross-platform); only the gateway worker needs Windows.
+--
+-- ApiKeySecretRef = env:GALAXY_MXGW_API_KEY → resolved at runtime by
+-- GalaxyDriver.ResolveApiKey. The env var is set on every driver-role
+-- container in docker-compose.yml.
+------------------------------------------------------------------------------
+
+IF NOT EXISTS (SELECT 1 FROM dbo.Namespace WHERE NamespaceId = 'MAIN-galaxy')
+    INSERT INTO dbo.Namespace
+        (NamespaceRowId, NamespaceId, ClusterId, Kind, NamespaceUri, Enabled, Notes)
+    VALUES
+        (NEWID(), 'MAIN-galaxy', 'MAIN', 'SystemPlatform',
+         'urn:zb:docker-dev:galaxy', 1,
+         'docker-dev seed — Galaxy / MXAccess namespace served by the MAIN cluster.');
+
+IF NOT EXISTS (SELECT 1 FROM dbo.DriverInstance WHERE DriverInstanceId = 'MAIN-galaxy-mxgw')
+    INSERT INTO dbo.DriverInstance
+        (DriverInstanceRowId, DriverInstanceId, ClusterId, NamespaceId, Name, DriverType, Enabled, DriverConfig)
+    VALUES
+        (NEWID(), 'MAIN-galaxy-mxgw', 'MAIN', 'MAIN-galaxy',
+         'MxAccess gateway (10.100.0.48:5120)', 'GalaxyMxGateway', 1,
+         N'{
+  "Gateway": {
+    "Endpoint": "http://10.100.0.48:5120",
+    "ApiKeySecretRef": "env:GALAXY_MXGW_API_KEY",
+    "UseTls": false,
+    "ConnectTimeoutSeconds": 10,
+    "DefaultCallTimeoutSeconds": 30
+  },
+  "MxAccess": {
+    "ClientName": "OtOpcUa-MAIN-docker-dev",
+    "PublishingIntervalMs": 1000
+  },
+  "Repository": {
+    "DiscoverPageSize": 5000,
+    "WatchDeployEvents": true
+  },
+  "Reconnect": {
+    "InitialBackoffMs": 500,
+    "MaxBackoffMs": 30000,
+    "ReplayOnSessionLost": true
+  }
+}');
+
+------------------------------------------------------------------------------
+-- Galaxy test tags — TestMachine_001.TestAlarm001..003
+--
+-- SystemPlatform-namespace tags have EquipmentId=NULL and use FolderPath +
+-- Name to address the MXAccess item. The Galaxy driver subscribes via the
+-- "FolderPath.Name" MXAccess reference form; OPC UA browse path is the
+-- equivalent "FolderPath/Name" under the SystemPlatform namespace.
+------------------------------------------------------------------------------
+
+IF NOT EXISTS (SELECT 1 FROM dbo.Tag WHERE TagId = 'MAIN-galaxy-TestMachine_001-TestAlarm001')
+    INSERT INTO dbo.Tag
+        (TagRowId, TagId, DriverInstanceId, DeviceId, EquipmentId, Name, FolderPath, DataType, AccessLevel, WriteIdempotent, PollGroupId, TagConfig)
+    VALUES
+        (NEWID(), 'MAIN-galaxy-TestMachine_001-TestAlarm001', 'MAIN-galaxy-mxgw', NULL, NULL,
+         'TestAlarm001', 'TestMachine_001', 'Boolean', 0, 0, NULL, N'{}');
+
+IF NOT EXISTS (SELECT 1 FROM dbo.Tag WHERE TagId = 'MAIN-galaxy-TestMachine_001-TestAlarm002')
+    INSERT INTO dbo.Tag
+        (TagRowId, TagId, DriverInstanceId, DeviceId, EquipmentId, Name, FolderPath, DataType, AccessLevel, WriteIdempotent, PollGroupId, TagConfig)
+    VALUES
+        (NEWID(), 'MAIN-galaxy-TestMachine_001-TestAlarm002', 'MAIN-galaxy-mxgw', NULL, NULL,
+         'TestAlarm002', 'TestMachine_001', 'Boolean', 0, 0, NULL, N'{}');
+
+IF NOT EXISTS (SELECT 1 FROM dbo.Tag WHERE TagId = 'MAIN-galaxy-TestMachine_001-TestAlarm003')
+    INSERT INTO dbo.Tag
+        (TagRowId, TagId, DriverInstanceId, DeviceId, EquipmentId, Name, FolderPath, DataType, AccessLevel, WriteIdempotent, PollGroupId, TagConfig)
+    VALUES
+        (NEWID(), 'MAIN-galaxy-TestMachine_001-TestAlarm003', 'MAIN-galaxy-mxgw', NULL, NULL,
+         'TestAlarm003', 'TestMachine_001', 'Boolean', 0, 0, NULL, N'{}');
+
+COMMIT TRANSACTION;
+
+------------------------------------------------------------------------------
+-- Summary (logged by sqlcmd output)
+------------------------------------------------------------------------------
+
+SELECT ClusterId, Name, NodeCount, RedundancyMode FROM dbo.ServerCluster ORDER BY ClusterId;
+SELECT NodeId, ClusterId, Host, OpcUaPort, ApplicationUri, ServiceLevelBase
+  FROM dbo.ClusterNode ORDER BY ClusterId, NodeId;
+SELECT NamespaceId, ClusterId, Kind, NamespaceUri FROM dbo.Namespace ORDER BY ClusterId, NamespaceId;
+SELECT DriverInstanceId, ClusterId, DriverType, NamespaceId, Name
+  FROM dbo.DriverInstance ORDER BY ClusterId, DriverInstanceId;
+SELECT TagId, DriverInstanceId, FolderPath, Name, DataType FROM dbo.Tag ORDER BY DriverInstanceId, FolderPath, Name;

docker-dev/traefik-dynamic.yml

@@ -1,6 +1,12 @@
-# docker-dev companion to scripts/install/traefik-dynamic.yml. Same routing rules,
-# but the upstream targets are the Compose service names (admin-a, admin-b) on
-# port 9000 instead of the Windows hostnames a bare-metal deployment would use.
+# docker-dev companion to scripts/install/traefik-dynamic.yml. Routes three
+# Akka clusters that share the Compose network:
+#
+#   - Main cluster (default): PathPrefix(`/`) → admin-a / admin-b.
+#   - Site A cluster:         Host(`site-a.localhost`) → site-a-1 / site-a-2.
+#   - Site B cluster:         Host(`site-b.localhost`) → site-b-1 / site-b-2.
+#
+# Host-header rules are more specific than PathPrefix, so they win over the
+# default router for the site hostnames automatically — no priority field needed.
 
 http:
   routers:
@@ -9,9 +15,27 @@ http:
       rule: "PathPrefix(`/`)"
       service: otopcua-admin
 
+    otopcua-site-a:
+      entryPoints: ["web"]
+      rule: "Host(`site-a.localhost`)"
+      service: otopcua-site-a
+
+    otopcua-site-b:
+      entryPoints: ["web"]
+      rule: "Host(`site-b.localhost`)"
+      service: otopcua-site-b
+
   services:
     otopcua-admin:
       loadBalancer:
+        # Blazor Server uses SignalR; the WebSocket upgrade must hit the same
+        # backend that owns the circuit ID. Sticky cookie keeps each session
+        # pinned to one node so the post-handshake WebSocket doesn't 404.
+        sticky:
+          cookie:
+            name: otopcua_lb
+            httpOnly: true
+            sameSite: lax
         servers:
           - url: "http://admin-a:9000"
           - url: "http://admin-b:9000"
@@ -19,3 +43,39 @@ http:
           path: /health/active
           interval: 5s
           timeout: 2s
+
+    otopcua-site-a:
+      loadBalancer:
+        # Blazor Server uses SignalR; the WebSocket upgrade must hit the same
+        # backend that owns the circuit ID. Sticky cookie keeps each session
+        # pinned to one node so the post-handshake WebSocket doesn't 404.
+        sticky:
+          cookie:
+            name: otopcua_lb
+            httpOnly: true
+            sameSite: lax
+        servers:
+          - url: "http://site-a-1:9000"
+          - url: "http://site-a-2:9000"
+        healthCheck:
+          path: /health/active
+          interval: 5s
+          timeout: 2s
+
+    otopcua-site-b:
+      loadBalancer:
+        # Blazor Server uses SignalR; the WebSocket upgrade must hit the same
+        # backend that owns the circuit ID. Sticky cookie keeps each session
+        # pinned to one node so the post-handshake WebSocket doesn't 404.
+        sticky:
+          cookie:
+            name: otopcua_lb
+            httpOnly: true
+            sameSite: lax
+        servers:
+          - url: "http://site-b-1:9000"
+          - url: "http://site-b-2:9000"
+        healthCheck:
+          path: /health/active
+          interval: 5s
+          timeout: 2s

docs/AddressSpace.md

@@ -1,6 +1,6 @@
 # Address Space
 
-Each driver's browsable subtree is built by streaming nodes from the driver's `ITagDiscovery.DiscoverAsync` implementation into an `IAddressSpaceBuilder`. `GenericDriverNodeManager` (`src/Core/ZB.MOM.WW.OtOpcUa.Core/OpcUa/GenericDriverNodeManager.cs`) owns the shared orchestration; `DriverNodeManager` (`src/Server/ZB.MOM.WW.OtOpcUa.Server/OpcUa/DriverNodeManager.cs`) implements `IAddressSpaceBuilder` against the OPC Foundation stack's `CustomNodeManager2`. The same code path serves Galaxy object hierarchies, Modbus PLC registers, AB CIP tags, TwinCAT symbols, FOCAS CNC parameters, and OPC UA Client aggregations — Galaxy is one driver of seven, not the driver.
+Each driver's browsable subtree is built by streaming nodes from the driver's `ITagDiscovery.DiscoverAsync` implementation into an `IAddressSpaceBuilder`. `GenericDriverNodeManager` (`src/Core/ZB.MOM.WW.OtOpcUa.Core/OpcUa/GenericDriverNodeManager.cs`) owns the shared orchestration; in v2 the SDK-driven materialization is handled by `OtOpcUaNodeManager` (`src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/OtOpcUaNodeManager.cs`) fed via `SdkAddressSpaceSink` (`src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/SdkAddressSpaceSink.cs`). The same code path serves Galaxy object hierarchies, Modbus PLC registers, AB CIP tags, TwinCAT symbols, FOCAS CNC parameters, and OPC UA Client aggregations — Galaxy is one driver of seven, not the driver.
 
 ## Driver root folder
 
@@ -66,7 +66,7 @@ Drivers that implement `IRediscoverable` fire `OnRediscoveryNeeded` when their b
 ## Key source files
 
 - `src/Core/ZB.MOM.WW.OtOpcUa.Core/OpcUa/GenericDriverNodeManager.cs` — orchestration + `CapturingBuilder`
-- `src/Server/ZB.MOM.WW.OtOpcUa.Server/OpcUa/DriverNodeManager.cs` — OPC UA materialization (`IAddressSpaceBuilder` impl + `NestedBuilder`)
+- `src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/OtOpcUaNodeManager.cs`, `src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/SdkAddressSpaceSink.cs` — OPC UA materialization (write-only sink fed by the actor system)
 - `src/Core/ZB.MOM.WW.OtOpcUa.Core.Abstractions/IAddressSpaceBuilder.cs` — builder contract
 - `src/Core/ZB.MOM.WW.OtOpcUa.Core.Abstractions/ITagDiscovery.cs` — driver discovery capability
 - `src/Core/ZB.MOM.WW.OtOpcUa.Core.Abstractions/DriverAttributeInfo.cs` — per-attribute descriptor

docs/AlarmTracking.md

@@ -15,9 +15,10 @@ historical reference.
 | **Galaxy sub-attribute fallback**  | `IWritable` writes to `$Alarm*` sub-attributes | gateway data subscription → driver `OnDataChange` → `DriverNodeManager` ConditionSink → `AlarmConditionService` |
 | **Scripted alarms**                | `Phase7EngineComposer` | server-side script evaluator → `Phase7EngineComposer.RouteToHistorianAsync` + `AlarmConditionService` |
 
-All three converge on `AlarmConditionService` (`src/Server/ZB.MOM.WW.OtOpcUa.Server/Alarms/AlarmConditionService.cs`),
-which owns the OPC UA Part 9 state machine and dispatches transitions
-to the OPC UA condition node managers. Driver-native transitions take
+All three converge on the alarm-state actor — in v2 the OPC UA Part 9 state
+machine lives inside `ScriptedAlarmActor`
+(`src/Server/ZB.MOM.WW.OtOpcUa.Runtime/ScriptedAlarms/ScriptedAlarmActor.cs`),
+which dispatches transitions to the OPC UA condition node managers. Driver-native transitions take
 precedence over sub-attribute synthesis when both arrive for the same
 condition — the dedup logic prefers the richer driver-native record
 because it carries the full operator + raise-time + category metadata

docs/IncrementalSync.md

@@ -28,7 +28,7 @@ Static drivers (Modbus, S7, AB CIP, AB Legacy, FOCAS) do not implement `IRedisco
 
 Tag-set changes authored in the Admin UI (UNS edits, CSV imports, driver-config edits) accumulate in a draft generation and commit via `sp_PublishGeneration`. The delta between the currently-published generation and the proposed next one is computed by `sp_ComputeGenerationDiff`, which drives:
 
-- The **DiffViewer** in Admin (`src/Server/ZB.MOM.WW.OtOpcUa.Admin/Components/Pages/Clusters/DiffViewer.razor`) so operators can preview what will change before clicking Publish.
+- The publish-preview surface in the Admin UI (`src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Components/Pages/Deployments.razor`, backed by `AdminOperationsClient`) so operators can preview what will change before clicking Publish.
 - The 409-on-stale-draft flow (decision #161) — a UNS drag-reorder preview carries a `DraftRevisionToken` so Confirm returns `409 Conflict / refresh-required` if the draft advanced between preview and commit.
 
 After publish, the server's generation applier invokes `IDriver.ReinitializeAsync(driverConfigJson, ct)` on every driver whose `DriverInstance.DriverConfig` row changed in the new generation. Reinitialize is the in-process recovery path for Tier A/B drivers; if it fails the driver is marked `DriverState.Faulted` and its nodes go Bad quality — but the server process stays running. See `docs/v2/driver-stability.md`.
@@ -64,6 +64,7 @@ Subscriptions for unchanged references stay live across rebuilds — their ref-c
 - `src/Core/ZB.MOM.WW.OtOpcUa.Core.Abstractions/IRediscoverable.cs` — backend-change capability
 - `src/Core/ZB.MOM.WW.OtOpcUa.Core/OpcUa/GenericDriverNodeManager.cs` — discovery orchestration
 - `src/Core/ZB.MOM.WW.OtOpcUa.Core.Abstractions/IDriver.cs` — `ReinitializeAsync` contract
-- `src/Server/ZB.MOM.WW.OtOpcUa.Admin/Services/GenerationService.cs` — publish-flow driver
+- `src/Server/ZB.MOM.WW.OtOpcUa.ControlPlane/Coordinators/ConfigPublishCoordinator.cs` — publish-flow driver
+- `src/Server/ZB.MOM.WW.OtOpcUa.ControlPlane/AdminOperations/AdminOperationsActor.cs` — cluster singleton invoked by the Admin UI's `AdminOperationsClient`
 - `docs/v2/config-db-schema.md` — `sp_PublishGeneration` + `sp_ComputeGenerationDiff`
 - `docs/v2/admin-ui.md` — DiffViewer + draft-revision-token flow

docs/OpcUaServer.md

@@ -1,13 +1,13 @@
 # OPC UA Server
 
-The OPC UA server component (`src/Server/ZB.MOM.WW.OtOpcUa.Server/OpcUa/OtOpcUaServer.cs`) hosts the OPC UA stack and exposes one browsable subtree per registered driver. The server itself is driver-agnostic — Galaxy/MXAccess, Modbus, S7, AB CIP, AB Legacy, TwinCAT, FOCAS, and OPC UA Client are all plugged in as `IDriver` implementations via the capability interfaces in `src/Core/ZB.MOM.WW.OtOpcUa.Core.Abstractions/`.
+The OPC UA server component (`src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/OtOpcUaSdkServer.cs`) hosts the OPC UA stack and exposes one browsable subtree per registered driver. The server itself is driver-agnostic — Galaxy/MXAccess, Modbus, S7, AB CIP, AB Legacy, TwinCAT, FOCAS, and OPC UA Client are all plugged in as `IDriver` implementations via the capability interfaces in `src/Core/ZB.MOM.WW.OtOpcUa.Core.Abstractions/`.
 
 ## Composition
 
 `OtOpcUaServer` subclasses the OPC Foundation `StandardServer` and wires:
 
 - A `DriverHost` (`src/Core/ZB.MOM.WW.OtOpcUa.Core/Hosting/DriverHost.cs`) which registers drivers and holds the per-instance `IDriver` references.
-- One `DriverNodeManager` per registered driver (`src/Server/ZB.MOM.WW.OtOpcUa.Server/OpcUa/DriverNodeManager.cs`), constructed in `CreateMasterNodeManager`. Each manager owns its own namespace URI (`urn:OtOpcUa:{DriverInstanceId}`) and exposes the driver as a subtree under the standard `Objects` folder.
+- One `DriverNodeManager` per registered driver (`src/Core/ZB.MOM.WW.OtOpcUa.Core/OpcUa/GenericDriverNodeManager.cs`), constructed in `CreateMasterNodeManager`. Each manager owns its own namespace URI (`urn:OtOpcUa:{DriverInstanceId}`) and exposes the driver as a subtree under the standard `Objects` folder.
 - A `CapabilityInvoker` (`src/Core/ZB.MOM.WW.OtOpcUa.Core/Resilience/CapabilityInvoker.cs`) per driver instance, keyed on `(DriverInstanceId, HostName, DriverCapability)` against the shared `DriverResiliencePipelineBuilder`. Every Read/Write/Discovery/Subscribe/HistoryRead/AlarmSubscribe call on the driver flows through this invoker so the Polly pipeline (retry / timeout / breaker / bulkhead) applies. The OTOPCUA0001 Roslyn analyzer enforces the wrapping at compile time.
 - An `IUserAuthenticator` (LDAP in production, injected stub in tests) for `UserName` token validation in the `ImpersonateUser` hook.
 - Optional `AuthorizationGate` + `NodeScopeResolver` (Phase 6.2) that sit in front of every dispatch call. In lax mode the gate passes through when the identity lacks LDAP groups so existing integration tests keep working; strict mode (`Authorization:StrictMode = true`) denies those cases.
@@ -50,7 +50,7 @@ The host name fed to the invoker comes from `IPerCallHostResolver.ResolveHost(fu
 
 ## Redundancy
 
-`Redundancy.Enabled = true` on the `ServerInstance` activates the `RedundancyCoordinator` + `ServiceLevelCalculator` (`src/Server/ZB.MOM.WW.OtOpcUa.Server/Redundancy/`). Standard OPC UA redundancy nodes (`Server/ServerRedundancy/RedundancySupport`, `ServerUriArray`, `Server/ServiceLevel`) are populated on startup; `ServiceLevel` recomputes whenever any driver's `DriverHealth` changes. The apply-lease mechanism prevents two instances from concurrently applying a generation. See `docs/Redundancy.md`.
+`Redundancy.Enabled = true` on the `ServerInstance` activates the `RedundancyStateActor` + `ServiceLevelCalculator` (`src/Server/ZB.MOM.WW.OtOpcUa.ControlPlane/Redundancy/`). Standard OPC UA redundancy nodes (`Server/ServerRedundancy/RedundancySupport`, `ServerUriArray`, `Server/ServiceLevel`) are populated on startup; `ServiceLevel` recomputes whenever any driver's `DriverHealth` changes. The apply-lease mechanism prevents two instances from concurrently applying a generation. See `docs/Redundancy.md`.
 
 ## Server class hierarchy
 
@@ -79,10 +79,11 @@ Certificate stores default to `%LOCALAPPDATA%\OPC Foundation\pki\` (directory-ba
 
 ## Key source files
 
-- `src/Server/ZB.MOM.WW.OtOpcUa.Server/OpcUa/OtOpcUaServer.cs` — `StandardServer` subclass + `ImpersonateUser` hook
-- `src/Server/ZB.MOM.WW.OtOpcUa.Server/OpcUa/DriverNodeManager.cs` — per-driver `CustomNodeManager2` + dispatch surface
-- `src/Server/ZB.MOM.WW.OtOpcUa.Server/OpcUa/OpcUaApplicationHost.cs` — programmatic `ApplicationConfiguration` + lifecycle
+- `src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/OtOpcUaSdkServer.cs` — `StandardServer` subclass
+- `src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/OpcUaApplicationHost.cs` — programmatic `ApplicationConfiguration` + lifecycle + `ImpersonateUser` hook
+- `src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/OtOpcUaNodeManager.cs` — SDK node manager + write-only address-space sink
+- `src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/SdkAddressSpaceSink.cs` — `IOpcUaAddressSpaceSink` adapter the actor system pushes into
+- `src/Core/ZB.MOM.WW.OtOpcUa.Core/OpcUa/GenericDriverNodeManager.cs` — per-driver discovery + dispatch surface
 - `src/Core/ZB.MOM.WW.OtOpcUa.Core/Hosting/DriverHost.cs` — driver registration
 - `src/Core/ZB.MOM.WW.OtOpcUa.Core/Resilience/CapabilityInvoker.cs` — Polly pipeline entry point
-- `src/Core/ZB.MOM.WW.OtOpcUa.Core/Authorization/` — Phase 6.2 permission trie + evaluator
-- `src/Server/ZB.MOM.WW.OtOpcUa.Server/Security/AuthorizationGate.cs` — stack-to-evaluator bridge
+- `src/Core/ZB.MOM.WW.OtOpcUa.Core/Authorization/` — permission trie + evaluator (`PermissionTrie`, `PermissionTrieCache`, `TriePermissionEvaluator`)

docs/README.md

@@ -59,7 +59,7 @@ For Modbus / S7 / AB CIP / AB Legacy / TwinCAT / FOCAS / OPC UA Client specifics
 | [security.md](security.md) | Transport security profiles, LDAP auth, ACL trie, role grants, OTOPCUA0001 analyzer |
 | [Redundancy.md](Redundancy.md) | `RedundancyCoordinator`, `ServiceLevelCalculator`, apply-lease, Prometheus metrics |
 | [Reservations.md](Reservations.md) | Fleet-wide ZTag / SAPID external-ID reservations — publish-time claim, release flow |
-| [ServiceHosting.md](ServiceHosting.md) | Two-process deploy (Server + Admin) install/uninstall, plus the optional `OtOpcUaWonderwareHistorian` sidecar |
+| [ServiceHosting.md](ServiceHosting.md) | Single fused `OtOpcUa.Host` binary install/uninstall with `OTOPCUA_ROLES` gating, plus the optional `OtOpcUaWonderwareHistorian` sidecar |
 | [StatusDashboard.md](StatusDashboard.md) | Pointer — superseded by [v2/admin-ui.md](v2/admin-ui.md) |
 
 ### Client tooling

docs/ReadWriteOperations.md

@@ -1,6 +1,6 @@
 # Read/Write Operations
 
-`DriverNodeManager` (`src/Server/ZB.MOM.WW.OtOpcUa.Server/OpcUa/DriverNodeManager.cs`) wires the OPC UA stack's per-variable `OnReadValue` and `OnWriteValue` hooks to each driver's `IReadable` and `IWritable` capabilities. Every dispatch flows through `CapabilityInvoker` so the Polly pipeline (retry / timeout / breaker / bulkhead) applies uniformly across Galaxy, Modbus, S7, AB CIP, AB Legacy, TwinCAT, FOCAS, and OPC UA Client drivers.
+`GenericDriverNodeManager` (`src/Core/ZB.MOM.WW.OtOpcUa.Core/OpcUa/GenericDriverNodeManager.cs`) wires the OPC UA stack's per-variable `OnReadValue` and `OnWriteValue` hooks to each driver's `IReadable` and `IWritable` capabilities. Every dispatch flows through `CapabilityInvoker` so the Polly pipeline (retry / timeout / breaker / bulkhead) applies uniformly across Galaxy, Modbus, S7, AB CIP, AB Legacy, TwinCAT, FOCAS, and OPC UA Client drivers.
 
 ## Driver vs virtual dispatch
 
@@ -60,8 +60,7 @@ Per decision #12, exceptions in the driver's capability call are logged and conv
 
 ## Key source files
 
-- `src/Server/ZB.MOM.WW.OtOpcUa.Server/OpcUa/DriverNodeManager.cs` — `OnReadValue` / `OnWriteValue` hooks
-- `src/Server/ZB.MOM.WW.OtOpcUa.Server/Security/WriteAuthzPolicy.cs` — classification-to-role policy
-- `src/Server/ZB.MOM.WW.OtOpcUa.Server/Security/AuthorizationGate.cs` — Phase 6.2 trie gate
+- `src/Core/ZB.MOM.WW.OtOpcUa.Core/OpcUa/GenericDriverNodeManager.cs` — `OnReadValue` / `OnWriteValue` hooks
+- `src/Core/ZB.MOM.WW.OtOpcUa.Core/Authorization/` — permission trie + evaluator (`PermissionTrie`, `PermissionTrieCache`, `TriePermissionEvaluator`) that gates Read/Write/Subscribe per the session's resolved LDAP groups
 - `src/Core/ZB.MOM.WW.OtOpcUa.Core/Resilience/CapabilityInvoker.cs` — `ExecuteAsync` / `ExecuteWriteAsync`
 - `src/Core/ZB.MOM.WW.OtOpcUa.Core.Abstractions/IReadable.cs`, `IWritable.cs`, `WriteIdempotentAttribute.cs`

docs/Redundancy.md

@@ -2,7 +2,9 @@
 
 ## Overview
 
-OtOpcUa supports OPC UA **non-transparent** warm/hot redundancy. Two or more `OtOpcUa.Host` processes run side-by-side, share the same Config DB, and join the same Akka.NET cluster. Each process owns a distinct `ApplicationUri`; OPC UA clients see both endpoints via the standard `ServerUriArray` and pick one based on the `ServiceLevel` byte that each server publishes.
+OtOpcUa supports OPC UA **non-transparent** warm/hot redundancy. Two or more `OtOpcUa.Host` processes run side-by-side, share the same Config DB, and join the same Akka.NET cluster. Each process owns a distinct `ApplicationUri`; OPC UA clients discover both endpoints by reading `Server.ServerArray` (NodeId `i=2254`) on either node and pick one based on the `ServiceLevel` byte that each server publishes.
+
+> **Discovery surface.** The `ServerArray` path on the `Server` object is what each node populates with self + peer `ApplicationUri`s — see `OpcUaApplicationHost.PopulateServerArray` and the per-node `PeerApplicationUris` option below. The redundancy-object-type `ServerUriArray` proper (a child of `Server.ServerRedundancy`) remains deferred pending an SDK object-type upgrade; clients should read `Server.ServerArray` for peer discovery today.
 
 > **v2 change.** v1's operator-managed `ClusterNode.RedundancyRole` column + `RedundancyCoordinator` / `ApplyLeaseRegistry` / `PeerHttpProbeLoop` are gone. Primary/secondary is now derived from **Akka cluster role-leader** for the `driver` role. The operator no longer writes a role into the DB; cluster topology + health drive ServiceLevel automatically.
 
@@ -78,6 +80,20 @@ Both nodes share the same `ConfigDb` connection string; `Cluster.PublicHostname`
 
 There is no longer a `Node:NodeId` setting, no `ClusterNode.RedundancyRole`, no `ServiceLevelBase`. NodeId is derived as `host:port` of the cluster `PublicHostname` (see `ClusterRoleInfo.LocalNode` for the formula).
 
+### Peer URI advertising
+
+Each node advertises its partner via `OpcUaApplicationHostOptions.PeerApplicationUris` (an `IList<string>`, default empty). `OpcUaApplicationHost.PopulateServerArray` appends each configured peer URI to the SDK's `IServerInternal.ServerUris` string table after server startup, so that `Server.ServerArray` reads served by `OnReadServerArray` return both self + peers. Set this per-node in `appsettings.json`:
+
+```json
+{
+  "OpcUaServer": {
+    "PeerApplicationUris": ["urn:node-b:OtOpcUa"]
+  }
+}
+```
+
+Node A lists Node B's `ApplicationUri` and vice-versa. Validated by `DualEndpointTests` in `tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.IntegrationTests/` — boots two `OpcUaApplicationHost` instances on loopback, asserts a real OPCFoundation client `Session` reading `Server.ServerArray` from Node A sees both URIs.
+
 ## Split-brain
 
 `akka.conf` configures Akka's split-brain resolver with `active-strategy = keep-oldest`, `stable-after = 15s`, and `failure-detector.threshold = 10.0`. Under a clean partition: the oldest member stays up + the smaller (or younger) side downs itself within ~15 seconds. The `RedundancyStateActor` on the surviving partition re-computes from the post-partition `Cluster.State`.

docs/ScriptedAlarms.md

@@ -111,13 +111,13 @@ Emissions map into `AlarmEventArgs` as `AlarmType = Kind.ToString()`, `SourceNod
 
 ## Composition
 
-`Phase7EngineComposer.Compose` (`src/Server/ZB.MOM.WW.OtOpcUa.Server/Phase7/Phase7EngineComposer.cs`) is the single call site that instantiates the engine. It takes the generation's `Script` / `VirtualTag` / `ScriptedAlarm` rows, the shared `CachedTagUpstreamSource`, an `IAlarmStateStore`, and an `IAlarmHistorianSink`, and returns a `Phase7ComposedSources` the caller owns. When `scriptedAlarms.Count > 0`:
+`Phase7Composer` (`src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/Phase7Composer.cs`) is the single call site that instantiates the engine. It takes the generation's `Script` / `VirtualTag` / `ScriptedAlarm` rows, the shared upstream-tag source, an `IAlarmStateStore`, and an `IAlarmHistorianSink`, and returns the composed sources the caller owns. When `scriptedAlarms.Count > 0`:
 
 1. `ProjectScriptedAlarms` resolves each row's `PredicateScriptId` against the script dictionary and produces a `ScriptedAlarmDefinition` list. Unknown or disabled scripts throw immediately — the DB publish guarantees referential integrity but this is a belt-and-braces check.
 2. A `ScriptedAlarmEngine` is constructed with the upstream source, the store, a shared `ScriptLoggerFactory` keyed to `scripts-*.log`, and the root Serilog logger.
 3. `alarmEngine.OnEvent` is wired to `RouteToHistorianAsync`, which projects each emission into an `AlarmHistorianEvent` and enqueues it on the sink. Fire-and-forget — the SQLite store-and-forward sink is already non-blocking.
 4. `LoadAsync(alarmDefs)` runs synchronously on the startup thread: it compiles every predicate, subscribes to the union of predicate inputs and message-template tokens, seeds the value cache, loads persisted state, re-derives `ActiveState` from a fresh predicate evaluation, and starts the 5s shelving timer. Compile failures are aggregated into one `InvalidOperationException` so operators see every bad predicate in one startup log line rather than one at a time.
-5. A `ScriptedAlarmSource` is created for the event stream, and a `ScriptedAlarmReadable` (`src/Server/ZB.MOM.WW.OtOpcUa.Server/Phase7/ScriptedAlarmReadable.cs`) is created for OPC UA variable reads on the alarm's active-state node (task #245) — unknown alarm ids return `BadNodeIdUnknown` rather than silently reading `false`.
+5. A `ScriptedAlarmSource` is created for the event stream; the v2 `ScriptedAlarmActor` (`src/Server/ZB.MOM.WW.OtOpcUa.Runtime/ScriptedAlarms/ScriptedAlarmActor.cs`) owns the active-state surface for OPC UA variable reads on the alarm's active-state node (task #245) — unknown alarm ids return `BadNodeIdUnknown` rather than silently reading `false`.
 
 Both engine and source are added to `Phase7ComposedSources.Disposables`, which `Phase7Composer` disposes on server shutdown.
 
@@ -132,5 +132,7 @@ Both engine and source are added to `Phase7ComposedSources.Disposables`, which `
 - `src/Core/ZB.MOM.WW.OtOpcUa.Core.ScriptedAlarms/AlarmTypes.cs` — `AlarmKind` + the four Part 9 enums
 - `src/Core/ZB.MOM.WW.OtOpcUa.Core.ScriptedAlarms/MessageTemplate.cs` — `{path}` placeholder resolver
 - `src/Core/ZB.MOM.WW.OtOpcUa.Core.ScriptedAlarms/IAlarmStateStore.cs` — persistence contract + `InMemoryAlarmStateStore` default
-- `src/Server/ZB.MOM.WW.OtOpcUa.Server/Phase7/Phase7EngineComposer.cs` — composition, config-row projection, historian routing
-- `src/Server/ZB.MOM.WW.OtOpcUa.Server/Phase7/ScriptedAlarmReadable.cs` — `IReadable` adapter exposing `ActiveState` to OPC UA variable reads
+- `src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/Phase7Composer.cs` — composition, config-row projection, historian routing
+- `src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/Phase7Applier.cs` — applies the composed Phase 7 plan into the SDK node manager
+- `src/Server/ZB.MOM.WW.OtOpcUa.Runtime/ScriptedAlarms/ScriptedAlarmActor.cs` — actor wrapper owning the alarm state machine and exposing `ActiveState` for OPC UA variable reads
+- `src/Server/ZB.MOM.WW.OtOpcUa.Host/Engines/RoslynScriptedAlarmEvaluator.cs` — production Roslyn predicate evaluator

docs/ServiceHosting.md

@@ -25,6 +25,16 @@ Galaxy access still uses the separately-installed **mxaccessgw** sidecar (see `d
 
 Single-node dev: `OTOPCUA_ROLES=admin,driver`. Production: typically two admin nodes (HA pair) + N driver nodes.
 
+### Per-role configuration overlays
+
+`Program.cs:33-35` builds a role suffix by joining the parsed roles **alphabetically** with `-` and loads `appsettings.{roleSuffix}.json` as an optional overlay on top of base `appsettings.json`. Three overlays ship in `src/Server/ZB.MOM.WW.OtOpcUa.Host/`:
+
+- `appsettings.admin.json` — admin-only nodes
+- `appsettings.driver.json` — driver-only nodes
+- `appsettings.admin-driver.json` — fused single-node dev / small deployments
+
+All three carry Serilog log-level overrides + `Security:Ldap:DevStubMode = false`. Loading order is **base `appsettings.json` → role overlay (`appsettings.{role}.json`) → environment overlay (`appsettings.{Environment}.json`)** — later layers win. Overlays are optional; the base file boots a node on its own.
+
 ## Akka cluster
 
 The host joins an Akka.NET cluster bound to the address in `appsettings.json::Cluster`:

docs/VirtualTags.md

@@ -107,13 +107,12 @@ Per [ADR-002](v2/implementation/adr-002-driver-vs-virtual-dispatch.md) Option B,
 
 `ITagUpstreamSource` and `IHistoryWriter` are the two ports the engine requires from its host. Both live in `Core.VirtualTags`. In the Server process:
 
-- **`CachedTagUpstreamSource`** (`src/Server/ZB.MOM.WW.OtOpcUa.Server/Phase7/CachedTagUpstreamSource.cs`) implements the interface (and the parallel `Core.ScriptedAlarms.ITagUpstreamSource` — identical shape, distinct namespace). A `ConcurrentDictionary<path, DataValueSnapshot>` cache. `Push(path, snapshot)` updates the cache and fans out synchronously to every observer. Reads of never-pushed paths return `BadNodeIdUnknown` quality (`UpstreamNotConfigured = 0x80340000`).
-- **`DriverSubscriptionBridge`** (`src/Server/ZB.MOM.WW.OtOpcUa.Server/Phase7/DriverSubscriptionBridge.cs`) feeds the cache. For each registered `ISubscribable` driver it batches a single `SubscribeAsync` for every fullRef the script graph references, installs an `OnDataChange` handler that translates driver-opaque fullRefs back to UNS paths via a reverse map, and pushes each delta into `CachedTagUpstreamSource`. Unsubscribes on dispose. The bridge suppresses `OTOPCUA0001` (the Roslyn analyzer that requires `ISubscribable` callers to go through `CapabilityInvoker`) on the documented basis that this is a lifecycle wiring, not per-evaluation hot path.
+- **Upstream-tag feed.** In v2 the upstream-tag feed is provided by the actor system. `DependencyMuxActor` (`src/Server/ZB.MOM.WW.OtOpcUa.Runtime/VirtualTags/DependencyMuxActor.cs`) multiplexes driver `ISubscribable` subscriptions for every fullRef the script graph references, translating driver-opaque fullRefs back to UNS paths via a reverse map. Deltas land on `VirtualTagActor` (`src/Server/ZB.MOM.WW.OtOpcUa.Runtime/VirtualTags/VirtualTagActor.cs`) as `DependencyValueChanged` messages; the actor's in-memory cache serves the engine's synchronous `GetTag` reads. Reads of never-pushed paths return `BadNodeIdUnknown` quality (`UpstreamNotConfigured = 0x80340000`).
 - **`IHistoryWriter`** — no production implementation is currently wired for virtual tags; `VirtualTagEngine` gets `NullHistoryWriter` by default from `Phase7EngineComposer`.
 
 ## Composition
 
-`Phase7Composer` (`src/Server/ZB.MOM.WW.OtOpcUa.Server/Phase7/Phase7Composer.cs`) is an `IAsyncDisposable` injected into `OpcUaServerService`:
+`Phase7Composer` (`src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/Phase7Composer.cs`) projects the published generation into a `Phase7Plan` that `Phase7Applier` applies to the running SDK node manager:
 
 1. `PrepareAsync(generationId, ct)` — called after the bootstrap generation loads and before `OpcUaApplicationHost.StartAsync`. Reads the `Script` / `VirtualTag` / `ScriptedAlarm` rows for that generation from the config DB (`OtOpcUaConfigDbContext`). Empty-config fast path returns `Phase7ComposedSources.Empty`.
 2. Constructs a `CachedTagUpstreamSource` + hands it to `Phase7EngineComposer.Compose`.
@@ -145,8 +144,9 @@ Definition reload on config publish: `VirtualTagEngine.Load` is re-entrant — a
 - `src/Core/ZB.MOM.WW.OtOpcUa.Core.VirtualTags/ITagUpstreamSource.cs` — driver-tag read + subscribe port
 - `src/Core/ZB.MOM.WW.OtOpcUa.Core.VirtualTags/IHistoryWriter.cs` — historize sink port + `NullHistoryWriter`
 - `src/Core/ZB.MOM.WW.OtOpcUa.Core.VirtualTags/VirtualTagSource.cs` — `IReadable` + `ISubscribable` adapter
-- `src/Server/ZB.MOM.WW.OtOpcUa.Server/Phase7/CachedTagUpstreamSource.cs` — production `ITagUpstreamSource`
-- `src/Server/ZB.MOM.WW.OtOpcUa.Server/Phase7/DriverSubscriptionBridge.cs` — driver `ISubscribable` → cache feed
-- `src/Server/ZB.MOM.WW.OtOpcUa.Server/Phase7/Phase7EngineComposer.cs` — row projection + engine instantiation
-- `src/Server/ZB.MOM.WW.OtOpcUa.Server/Phase7/Phase7Composer.cs` — lifecycle host: load rows, compose, wire bridge
-- `src/Server/ZB.MOM.WW.OtOpcUa.Server/OpcUa/DriverNodeManager.cs` — `SelectReadable` + `IsWriteAllowedBySource` dispatch kernel
+- `src/Server/ZB.MOM.WW.OtOpcUa.Runtime/VirtualTags/VirtualTagActor.cs` — actor wrapper that owns per-instance state and the synchronous read cache
+- `src/Server/ZB.MOM.WW.OtOpcUa.Runtime/VirtualTags/DependencyMuxActor.cs` — driver `ISubscribable` → actor feed (replaces the v1 `DriverSubscriptionBridge`)
+- `src/Server/ZB.MOM.WW.OtOpcUa.Host/Engines/RoslynVirtualTagEvaluator.cs` — production Roslyn evaluator wired into the actor
+- `src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/Phase7Composer.cs` — row projection + engine instantiation (`Phase7Plan` composer)
+- `src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/Phase7Applier.cs` — applies the composed plan into the SDK node manager
+- `src/Core/ZB.MOM.WW.OtOpcUa.Core/OpcUa/GenericDriverNodeManager.cs` — driver-vs-virtual dispatch kernel

docs/drivers/OpcUaClient-Test-Fixture.md

@@ -136,9 +136,10 @@ ConditionType events (non-base `BaseEventType`) is not verified.
 ## Follow-up candidates
 
 The easiest win here is to **wire the client driver tests against this
-repo's own server**. The integration test project
-`tests/Server/ZB.MOM.WW.OtOpcUa.Server.Tests/OpcUaServerIntegrationTests.cs`
-already stands up a real OPC UA server on a non-default port with a seeded
+repo's own server**. The v2 integration test project
+`tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.IntegrationTests/DualEndpointTests.cs`
+(the v2 replacement for the retired v1 `OpcUaServerIntegrationTests`) already
+stands up a real OPC UA server on a non-default port with a seeded
 FakeDriver. An `OpcUaClientLiveLoopbackTests` that connects the client
 driver to that server would give:
 
@@ -165,6 +166,6 @@ Beyond that:
   mocked `Session`
 - `src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.OpcUaClient/OpcUaClientDriver.cs` — ctor +
   session-factory seam tests mock through
-- `tests/Server/ZB.MOM.WW.OtOpcUa.Server.Tests/OpcUaServerIntegrationTests.cs` —
-  the server-side integration harness a future loopback client test could
-  piggyback on
+- `tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.IntegrationTests/DualEndpointTests.cs` —
+  the v2 dual-endpoint integration harness a future loopback client test could
+  piggyback on (v1 `OpcUaServerIntegrationTests.cs` retired with the v1 server project)

docs/plans/2026-05-26-akka-hosting-alignment-gaps-closeout.md

@@ -0,0 +1,716 @@
+# Akka Hosting Alignment — Gap Closeout Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use `superpowers-extended-cc:executing-plans` to implement this plan task-by-task.
+
+**Goal:** Close the four real/cosmetic gaps identified by the audit of `docs/plans/2026-05-26-akka-hosting-alignment-plan.md` so the v2 implementation matches the plan's literal contract (per-role appsettings overlays, explicit dual-endpoint visibility test, plan-prescribed filenames, removal of empty legacy directories).
+
+**Architecture:** Additive only. No production-runtime semantics change. One small extension to `OpcUaApplicationHost` so the OPC UA server can advertise peer URIs in `Server.ServerArray` — gated on a new option, defaults to old behavior. Everything else is JSON, test code, file moves, and `rm -rf` of stale bin/obj trees.
+
+**Tech Stack:** .NET 10, OPCFoundation .NET Standard SDK (`Opc.Ua.*`), xunit.v3, Shouldly, EF Core 10 (inherited; no schema changes).
+
+**Source plan:** `docs/plans/2026-05-26-akka-hosting-alignment-plan.md`. The audit findings closed by this plan map to Tasks 54, 59, 60, and the post-Task-56 cosmetic cleanup. **Read the source plan's "Conventions for every task" block — those rules still apply here.**
+
+**Branch:** `v2-gap-closeout` off `master`.
+
+---
+
+## Conventions for every task
+
+- **Branch:** Stay on `v2-gap-closeout`. Never commit to `master` while plan is running.
+- **Build command:** `dotnet build ZB.MOM.WW.OtOpcUa.slnx` — must be green before commit.
+- **Test command:** `dotnet test ZB.MOM.WW.OtOpcUa.slnx --no-build` — relevant new/changed tests must pass.
+- **Commit format:** Conventional Commits matching the source plan — `feat(host):`, `test(opcua):`, `chore(cleanup):`, `refactor(test):`, etc.
+- **Mac compatibility:** All code must build on macOS. The new dual-endpoint test boots two real OPC UA servers on loopback — works on macOS (no Windows-only APIs needed; PKI is created under a per-test temp dir).
+
+---
+
+## Task 0: Add three role-overlay appsettings files (Task 54 gap)
+
+**Classification:** small
+**Estimated implement time:** ~3 min
+**Parallelizable with:** Task 1, Task 5, Task 6
+
+**Files:**
+- Create: `/Users/dohertj2/Desktop/OtOpcUa/src/Server/ZB.MOM.WW.OtOpcUa.Host/appsettings.admin.json`
+- Create: `/Users/dohertj2/Desktop/OtOpcUa/src/Server/ZB.MOM.WW.OtOpcUa.Host/appsettings.driver.json`
+- Create: `/Users/dohertj2/Desktop/OtOpcUa/src/Server/ZB.MOM.WW.OtOpcUa.Host/appsettings.admin-driver.json`
+
+**Background:**
+`Program.cs` line 33-35 loads `appsettings.{role-suffix}.json` where the suffix is the roles joined alphabetically with `'-'`. Today the loader passes `optional: true`, so the host boots without these files — but the source plan (Task 54) called them out as required scaffolding so operators have per-role tunable defaults.
+
+Suffix matrix:
+| `OTOPCUA_ROLES` env | Loaded file |
+|---|---|
+| `admin` | `appsettings.admin.json` |
+| `driver` | `appsettings.driver.json` |
+| `admin,driver` (any order) | `appsettings.admin-driver.json` (joined alphabetical) |
+
+**Step 1: Create `appsettings.admin.json`**
+
+Admin-only nodes don't bind drivers; tighten Serilog and disable the LDAP dev stub by default.
+
+```json
+{
+  "Serilog": {
+    "MinimumLevel": {
+      "Default": "Information",
+      "Override": {
+        "Microsoft.AspNetCore": "Warning",
+        "Akka": "Information"
+      }
+    }
+  },
+  "Security": {
+    "Ldap": {
+      "DevStubMode": false
+    }
+  }
+}
+```
+
+**Step 2: Create `appsettings.driver.json`**
+
+Driver-only nodes have no Admin UI; raise OPC UA verbosity slightly so per-node diagnostics flow to logs.
+
+```json
+{
+  "Serilog": {
+    "MinimumLevel": {
+      "Default": "Information",
+      "Override": {
+        "Opc.Ua": "Debug",
+        "Akka": "Information"
+      }
+    }
+  },
+  "Security": {
+    "Ldap": {
+      "DevStubMode": false
+    }
+  }
+}
+```
+
+**Step 3: Create `appsettings.admin-driver.json`**
+
+Combined-role nodes (the docker-dev compose default + the integration test harness) — turn on both surfaces with shared defaults.
+
+```json
+{
+  "Serilog": {
+    "MinimumLevel": {
+      "Default": "Information",
+      "Override": {
+        "Microsoft.AspNetCore": "Warning",
+        "Opc.Ua": "Information",
+        "Akka": "Information"
+      }
+    }
+  },
+  "Security": {
+    "Ldap": {
+      "DevStubMode": false
+    }
+  }
+}
+```
+
+**Step 4: Build green check**
+
+Run: `dotnet build ZB.MOM.WW.OtOpcUa.slnx`
+Expected: succeeds. (JSON files do not break the build; this is a smoke check that nothing else regressed.)
+
+**Step 5: Commit**
+
+```bash
+git add src/Server/ZB.MOM.WW.OtOpcUa.Host/appsettings.admin.json \
+        src/Server/ZB.MOM.WW.OtOpcUa.Host/appsettings.driver.json \
+        src/Server/ZB.MOM.WW.OtOpcUa.Host/appsettings.admin-driver.json
+git commit -m "feat(host): add per-role appsettings overlays for admin/driver/admin-driver"
+```
+
+---
+
+## Task 1: Extend `OpcUaApplicationHost` with `PeerApplicationUris` + populate `Server.ServerArray`
+
+**Classification:** standard
+**Estimated implement time:** ~5 min
+**Parallelizable with:** Task 0, Task 5, Task 6
+
+**Files:**
+- Modify: `/Users/dohertj2/Desktop/OtOpcUa/src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/OpcUaApplicationHost.cs` (add option + post-start population)
+- Test: `/Users/dohertj2/Desktop/OtOpcUa/tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.Tests/OpcUaApplicationHostServerArrayTests.cs`
+
+**Background:**
+The source plan's Task 60 promised a test where "real OPCFoundation client → both endpoints visible in ServerUriArray". That requires production code to populate the peer URIs onto each server's `Server.ServerArray` (NodeId i=2254) property. No such code exists in v2 today — this task adds it as an opt-in option so existing single-node tests keep their current behavior. Task 3 then writes the integration test that drives it across two servers.
+
+**Step 1: Write the failing unit test**
+
+Create `tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.Tests/OpcUaApplicationHostServerArrayTests.cs`:
+
+```csharp
+using System.IO;
+using System.Net.Sockets;
+using System.Net;
+using Microsoft.Extensions.Logging.Abstractions;
+using Opc.Ua;
+using Opc.Ua.Server;
+using Shouldly;
+using Xunit;
+using ZB.MOM.WW.OtOpcUa.OpcUaServer;
+
+namespace ZB.MOM.WW.OtOpcUa.OpcUaServer.Tests;
+
+/// <summary>
+/// Audit gap closeout — verifies <see cref="OpcUaApplicationHostOptions.PeerApplicationUris"/>
+/// is reflected in <c>Server.ServerArray</c> after start. Single-server in-process check; the
+/// cross-server visibility check lives in <c>OtOpcUa.OpcUaServer.IntegrationTests</c>.
+/// </summary>
+public sealed class OpcUaApplicationHostServerArrayTests
+{
+    [Fact]
+    public async Task ServerArray_contains_local_uri_and_configured_peers_after_start()
+    {
+        var pkiRoot = Path.Combine(Path.GetTempPath(), $"otopcua-pki-{Guid.NewGuid():N}");
+        try
+        {
+            var options = new OpcUaApplicationHostOptions
+            {
+                ApplicationName = "OtOpcUa.UnitTest",
+                ApplicationUri = "urn:OtOpcUa.UnitTest.NodeA",
+                OpcUaPort = AllocateFreePort(),
+                PublicHostname = "127.0.0.1",
+                PkiStoreRoot = pkiRoot,
+                PeerApplicationUris = new[] { "urn:OtOpcUa.UnitTest.NodeB" },
+            };
+
+            var server = new StandardServer();
+            await using var host = new OpcUaApplicationHost(options, NullLogger<OpcUaApplicationHost>.Instance);
+            await host.StartAsync(server, CancellationToken.None);
+
+            var serverArray = server.CurrentInstance.ServerObject.ServerArray.Value;
+            serverArray.ShouldNotBeNull();
+            serverArray.ShouldContain("urn:OtOpcUa.UnitTest.NodeA");
+            serverArray.ShouldContain("urn:OtOpcUa.UnitTest.NodeB");
+        }
+        finally
+        {
+            if (Directory.Exists(pkiRoot)) Directory.Delete(pkiRoot, recursive: true);
+        }
+    }
+
+    private static int AllocateFreePort()
+    {
+        var listener = new TcpListener(IPAddress.Loopback, 0);
+        listener.Start();
+        var port = ((IPEndPoint)listener.LocalEndpoint).Port;
+        listener.Stop();
+        return port;
+    }
+}
+```
+
+**Step 2: Run the test — confirm it fails**
+
+Run: `dotnet test tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.Tests --filter "FullyQualifiedName~OpcUaApplicationHostServerArrayTests"`
+Expected: FAIL with `PeerApplicationUris` not found (compile error) — the option doesn't exist yet.
+
+**Step 3: Add the option**
+
+Edit `src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/OpcUaApplicationHost.cs`. Add to `OpcUaApplicationHostOptions` (after `AutoAcceptUntrustedClientCertificates`, around line 65):
+
+```csharp
+/// <summary>
+/// Peer server URIs published in <c>Server.ServerArray</c> after start, in addition to
+/// the local <see cref="ApplicationUri"/>. Empty by default — set this on warm-redundancy
+/// deployments so OPC UA clients can discover the partner endpoint via the standard
+/// Server.ServerArray property (NodeId i=2254). Order does not matter; the local URI
+/// is always element 0.
+/// </summary>
+public IList<string> PeerApplicationUris { get; set; } = new List<string>();
+```
+
+**Step 4: Populate `Server.ServerArray` after start**
+
+Edit `OpcUaApplicationHost.StartAsync` (around line 100-118). After the `_application.Start(server)` call and before the log line, insert:
+
+```csharp
+PopulateServerArray();
+```
+
+Then add the private method below `AttachUserAuthenticator`:
+
+```csharp
+/// <summary>
+/// Writes the union of <see cref="OpcUaApplicationHostOptions.ApplicationUri"/> and
+/// <see cref="OpcUaApplicationHostOptions.PeerApplicationUris"/> to the OPC UA standard
+/// <c>Server.ServerArray</c> property (NodeId i=2254). Clients in a warm-redundancy
+/// deployment discover the partner endpoint by reading this property.
+/// </summary>
+private void PopulateServerArray()
+{
+    var serverObject = _server?.CurrentInstance?.ServerObject;
+    if (serverObject is null) return;
+
+    var uris = new List<string> { _options.ApplicationUri };
+    foreach (var peer in _options.PeerApplicationUris)
+    {
+        if (!string.IsNullOrWhiteSpace(peer) && !uris.Contains(peer))
+            uris.Add(peer);
+    }
+    serverObject.ServerArray.Value = uris.ToArray();
+}
+```
+
+**Step 5: Run the test — confirm it passes**
+
+Run: `dotnet test tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.Tests --filter "FullyQualifiedName~OpcUaApplicationHostServerArrayTests"`
+Expected: PASS. If `ServerObject.ServerArray.Value` is read-only (some SDK versions guard it), fall back to writing through `ServerArrayNode.Value` via the address-space accessor — but try the direct write first; the SDK exposes it as a settable BaseDataVariableState on `ServerObjectState`.
+
+**Step 6: Run full OpcUaServer.Tests suite to confirm no regression**
+
+Run: `dotnet test tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.Tests`
+Expected: all tests pass — `PopulateServerArray` is additive when `PeerApplicationUris` is empty (default), so existing tests don't change behavior.
+
+**Step 7: Commit**
+
+```bash
+git add src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/OpcUaApplicationHost.cs \
+        tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.Tests/OpcUaApplicationHostServerArrayTests.cs
+git commit -m "feat(opcua): OpcUaApplicationHost publishes peer URIs in Server.ServerArray"
+```
+
+---
+
+## Task 2: Create `OtOpcUa.OpcUaServer.IntegrationTests` project
+
+**Classification:** small
+**Estimated implement time:** ~4 min
+**Parallelizable with:** Task 5, Task 6 (file moves elsewhere)
+**Depends on:** none (csproj is self-contained)
+
+**Files:**
+- Create: `/Users/dohertj2/Desktop/OtOpcUa/tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.IntegrationTests/ZB.MOM.WW.OtOpcUa.OpcUaServer.IntegrationTests.csproj`
+- Modify: `/Users/dohertj2/Desktop/OtOpcUa/ZB.MOM.WW.OtOpcUa.slnx` (add the project)
+
+**Background:**
+The source plan's Task 60 named this exact project. Audit found ServiceLevel coverage relocated to other test projects but no `OpcUaServer.IntegrationTests` project exists. Creating the project skeleton in its own task keeps Task 3's commit focused on the test code.
+
+**Step 1: Create the csproj**
+
+Mirror the conventions in `tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.Tests/ZB.MOM.WW.OtOpcUa.OpcUaServer.Tests.csproj`. The integration project needs the `Opc.Ua.Client` package (vs. only `Opc.Ua.Server` in the unit tests) — confirm the version against the existing client CLI's csproj: `src/Client/ZB.MOM.WW.OtOpcUa.Client.CLI/ZB.MOM.WW.OtOpcUa.Client.CLI.csproj`.
+
+```xml
+<Project Sdk="Microsoft.NET.Sdk">
+
+    <PropertyGroup>
+        <IsPackable>false</IsPackable>
+        <IsTestProject>true</IsTestProject>
+        <RootNamespace>ZB.MOM.WW.OtOpcUa.OpcUaServer.IntegrationTests</RootNamespace>
+        <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+    </PropertyGroup>
+
+    <ItemGroup>
+        <PackageReference Include="xunit.v3"/>
+        <PackageReference Include="Shouldly"/>
+        <PackageReference Include="Microsoft.NET.Test.Sdk"/>
+        <PackageReference Include="OPCFoundation.NetStandard.Opc.Ua.Client"/>
+        <PackageReference Include="OPCFoundation.NetStandard.Opc.Ua.Configuration"/>
+        <PackageReference Include="Microsoft.Extensions.Logging.Abstractions"/>
+        <PackageReference Include="xunit.runner.visualstudio">
+            <PrivateAssets>all</PrivateAssets>
+            <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+        </PackageReference>
+    </ItemGroup>
+
+    <ItemGroup>
+        <ProjectReference Include="..\..\..\src\Server\ZB.MOM.WW.OtOpcUa.OpcUaServer\ZB.MOM.WW.OtOpcUa.OpcUaServer.csproj"/>
+    </ItemGroup>
+
+</Project>
+```
+
+If `OPCFoundation.NetStandard.Opc.Ua.Client` isn't in `Directory.Packages.props`, add it there (mirror the existing `OPCFoundation.NetStandard.Opc.Ua.Server` version exactly).
+
+**Step 2: Add project to the solution**
+
+Run: `dotnet sln ZB.MOM.WW.OtOpcUa.slnx add tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.IntegrationTests/ZB.MOM.WW.OtOpcUa.OpcUaServer.IntegrationTests.csproj`
+Expected: "Project added to the solution."
+
+**Step 3: Build green check**
+
+Run: `dotnet build ZB.MOM.WW.OtOpcUa.slnx`
+Expected: builds. (Empty project, so no test discovery yet — `dotnet test` would say "no tests".)
+
+**Step 4: Commit**
+
+```bash
+git add tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.IntegrationTests/ \
+        ZB.MOM.WW.OtOpcUa.slnx \
+        Directory.Packages.props  # only if the Opc.Ua.Client version was added there
+git commit -m "test(opcua): scaffold OtOpcUa.OpcUaServer.IntegrationTests project"
+```
+
+---
+
+## Task 3: `DualEndpointTests` — real OPC UA client reads both URIs from `Server.ServerArray`
+
+**Classification:** standard
+**Estimated implement time:** ~5 min
+**Parallelizable with:** Task 5, Task 6
+**Depends on:** Task 1 (PeerApplicationUris wiring), Task 2 (IT project exists)
+
+**Files:**
+- Create: `/Users/dohertj2/Desktop/OtOpcUa/tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.IntegrationTests/DualEndpointTests.cs`
+
+**Background:**
+This is the explicit Task 60 deliverable: a real OPC UA client connects to one server and confirms it can discover the partner via `Server.ServerArray`. Single-server unit-side coverage exists in Task 1; this test exercises the wire path with both servers up.
+
+**Step 1: Write the test**
+
+```csharp
+using System.Net;
+using System.Net.Sockets;
+using Microsoft.Extensions.Logging.Abstractions;
+using Opc.Ua;
+using Opc.Ua.Client;
+using Opc.Ua.Configuration;
+using Opc.Ua.Server;
+using Shouldly;
+using Xunit;
+using ZB.MOM.WW.OtOpcUa.OpcUaServer;
+
+namespace ZB.MOM.WW.OtOpcUa.OpcUaServer.IntegrationTests;
+
+/// <summary>
+/// Source plan Task 60 — closes the audit gap. Boots two real <see cref="StandardServer"/>
+/// instances on loopback, each configured with the other's <c>ApplicationUri</c> in
+/// <see cref="OpcUaApplicationHostOptions.PeerApplicationUris"/>. A real OPC UA client connects
+/// to Node A, reads <c>Server.ServerArray</c>, and asserts both URIs are visible — the
+/// warm-redundancy discovery contract clients depend on.
+/// </summary>
+public sealed class DualEndpointTests
+{
+    private const string NodeAUri = "urn:OtOpcUa.DualEndpoint.NodeA";
+    private const string NodeBUri = "urn:OtOpcUa.DualEndpoint.NodeB";
+
+    [Fact]
+    public async Task Client_reads_both_ApplicationUris_from_NodeA_ServerArray()
+    {
+        var pkiRootA = Path.Combine(Path.GetTempPath(), $"otopcua-pki-a-{Guid.NewGuid():N}");
+        var pkiRootB = Path.Combine(Path.GetTempPath(), $"otopcua-pki-b-{Guid.NewGuid():N}");
+        var portA = AllocateFreePort();
+        var portB = AllocateFreePort();
+
+        try
+        {
+            await using var nodeA = await StartNodeAsync(NodeAUri, portA, pkiRootA, peers: new[] { NodeBUri });
+            await using var nodeB = await StartNodeAsync(NodeBUri, portB, pkiRootB, peers: new[] { NodeAUri });
+
+            var serverArray = await ReadServerArrayAsync($"opc.tcp://127.0.0.1:{portA}/OtOpcUa");
+            serverArray.ShouldContain(NodeAUri);
+            serverArray.ShouldContain(NodeBUri);
+        }
+        finally
+        {
+            if (Directory.Exists(pkiRootA)) Directory.Delete(pkiRootA, recursive: true);
+            if (Directory.Exists(pkiRootB)) Directory.Delete(pkiRootB, recursive: true);
+        }
+    }
+
+    private static async Task<OpcUaApplicationHost> StartNodeAsync(
+        string applicationUri, int port, string pkiRoot, string[] peers)
+    {
+        var options = new OpcUaApplicationHostOptions
+        {
+            ApplicationName = applicationUri,           // unique per node — SDK uses it for cert CN
+            ApplicationUri = applicationUri,
+            OpcUaPort = port,
+            PublicHostname = "127.0.0.1",
+            PkiStoreRoot = pkiRoot,
+            EnabledSecurityProfiles = new List<OpcUaSecurityProfile> { OpcUaSecurityProfile.None },
+            AutoAcceptUntrustedClientCertificates = true,
+            PeerApplicationUris = peers,
+        };
+        var server = new StandardServer();
+        var host = new OpcUaApplicationHost(options, NullLogger<OpcUaApplicationHost>.Instance);
+        await host.StartAsync(server, CancellationToken.None);
+        return host;
+    }
+
+    private static async Task<string[]> ReadServerArrayAsync(string endpointUrl)
+    {
+        var appConfig = new ApplicationConfiguration
+        {
+            ApplicationName = "OtOpcUa.DualEndpointClient",
+            ApplicationUri = $"urn:OtOpcUa.DualEndpointClient.{Guid.NewGuid():N}",
+            ApplicationType = ApplicationType.Client,
+            SecurityConfiguration = new SecurityConfiguration
+            {
+                ApplicationCertificate = new CertificateIdentifier(),
+                AutoAcceptUntrustedCertificates = true,
+            },
+            ClientConfiguration = new ClientConfiguration { DefaultSessionTimeout = 60_000 },
+            CertificateValidator = new CertificateValidator(),
+        };
+        await appConfig.Validate(ApplicationType.Client);
+        appConfig.CertificateValidator.CertificateValidation += (_, e) => e.Accept = true;
+
+        var endpoint = CoreClientUtils.SelectEndpoint(appConfig, endpointUrl, useSecurity: false);
+        var endpointConfiguration = EndpointConfiguration.Create(appConfig);
+        var configuredEndpoint = new ConfiguredEndpoint(null, endpoint, endpointConfiguration);
+
+        using var session = await Session.Create(
+            appConfig, configuredEndpoint, updateBeforeConnect: false,
+            sessionName: "DualEndpointTests", sessionTimeout: 60_000,
+            identity: new UserIdentity(new AnonymousIdentityToken()),
+            preferredLocales: null);
+
+        var value = session.ReadValue(VariableIds.Server_ServerArray);
+        return (string[])value.Value;
+    }
+
+    private static int AllocateFreePort()
+    {
+        var listener = new TcpListener(IPAddress.Loopback, 0);
+        listener.Start();
+        var port = ((IPEndPoint)listener.LocalEndpoint).Port;
+        listener.Stop();
+        return port;
+    }
+}
+```
+
+**Step 2: Run the test**
+
+Run: `dotnet test tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.IntegrationTests`
+Expected: PASS. Wall-time ~3-5 s (two cert-creation cycles + session handshake).
+
+If the test hangs on the session handshake on first run, it's the SDK reading the trusted-cert store — bumping `AutoAcceptUntrustedClientCertificates = true` on both server hosts (already set above) should resolve it. If `CoreClientUtils.SelectEndpoint` throws because the SDK version uses a different overload, fall back to constructing the `EndpointDescription` directly with `EndpointUrl = endpointUrl, SecurityMode = MessageSecurityMode.None, SecurityPolicyUri = SecurityPolicies.None` and skipping `SelectEndpoint`.
+
+**Step 3: Commit**
+
+```bash
+git add tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.IntegrationTests/DualEndpointTests.cs
+git commit -m "test(opcua): DualEndpointTests — real client reads peer URIs from Server.ServerArray"
+```
+
+---
+
+## Task 4: Wire `OtOpcUa.OpcUaServer.IntegrationTests` into v2-ci.yml
+
+**Classification:** small
+**Estimated implement time:** ~3 min
+**Parallelizable with:** Task 5, Task 6
+**Depends on:** Task 3 (project must exist + have a real test before CI runs it)
+
+**Files:**
+- Modify: `/Users/dohertj2/Desktop/OtOpcUa/.github/workflows/v2-ci.yml`
+
+**Step 1: Add the project to the `integration` job**
+
+Either extend the existing `integration` job to run a second `dotnet test` step, or convert it to a matrix. Prefer a matrix for symmetry with `unit-tests`:
+
+Open `.github/workflows/v2-ci.yml`, locate the `integration:` job. Replace it with:
+
+```yaml
+  integration:
+    needs: build
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        project:
+          - tests/Server/ZB.MOM.WW.OtOpcUa.Host.IntegrationTests
+          - tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.IntegrationTests
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: 10.0.x
+      - name: dotnet test ${{ matrix.project }}
+        run: dotnet test ${{ matrix.project }} --configuration Release --filter "Category!=E2E"
+```
+
+**Step 2: Build green check**
+
+Run: `dotnet test tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.IntegrationTests --configuration Release --filter "Category!=E2E"`
+Expected: matches the exact CI command — passes locally so CI will pass too.
+
+**Step 3: Commit**
+
+```bash
+git add .github/workflows/v2-ci.yml
+git commit -m "ci(v2): include OpcUaServer.IntegrationTests in integration matrix"
+```
+
+---
+
+## Task 5: Rename `FailoverScenarioTests` → `FailoverDuringDeployTests` (Task 59 cosmetic)
+
+**Classification:** trivial
+**Estimated implement time:** ~2 min
+**Parallelizable with:** Task 0, Task 1, Task 2, Task 6 (different files)
+
+**Files:**
+- Rename: `tests/Server/ZB.MOM.WW.OtOpcUa.Host.IntegrationTests/FailoverScenarioTests.cs` → `FailoverDuringDeployTests.cs`
+- Modify: class name + namespace-internal references
+
+**Step 1: Rename the file and the class**
+
+```bash
+git mv tests/Server/ZB.MOM.WW.OtOpcUa.Host.IntegrationTests/FailoverScenarioTests.cs \
+       tests/Server/ZB.MOM.WW.OtOpcUa.Host.IntegrationTests/FailoverDuringDeployTests.cs
+```
+
+Then edit `FailoverDuringDeployTests.cs` and replace the single class declaration `public sealed class FailoverScenarioTests` with `public sealed class FailoverDuringDeployTests`. Use Edit, not sed — the file only declares this class once (`grep -c "FailoverScenario" .` ≤ 2).
+
+**Step 2: Sweep for any stale references**
+
+Run: `grep -rln "FailoverScenarioTests" .`
+Expected: zero matches after Step 1. If anything appears (e.g., a CI filter, a doc), fix the reference.
+
+**Step 3: Build + run test**
+
+Run: `dotnet test tests/Server/ZB.MOM.WW.OtOpcUa.Host.IntegrationTests --filter "FullyQualifiedName~FailoverDuringDeployTests"`
+Expected: same tests pass that previously passed under the old name.
+
+**Step 4: Commit**
+
+```bash
+git add tests/Server/ZB.MOM.WW.OtOpcUa.Host.IntegrationTests/FailoverDuringDeployTests.cs
+git commit -m "refactor(test): rename FailoverScenarioTests → FailoverDuringDeployTests for plan parity"
+```
+
+---
+
+## Task 6: Delete empty bin/obj-only legacy directories
+
+**Classification:** trivial
+**Estimated implement time:** ~2 min
+**Parallelizable with:** Task 0, Task 1, Task 2, Task 5
+
+**Files:**
+- Delete: `src/Server/ZB.MOM.WW.OtOpcUa.Server/`
+- Delete: `src/Server/ZB.MOM.WW.OtOpcUa.Admin/`
+- Delete: `tests/Server/ZB.MOM.WW.OtOpcUa.Server.Tests/`
+- Delete: `tests/Server/ZB.MOM.WW.OtOpcUa.Admin.Tests/`
+- Delete: `tests/Server/ZB.MOM.WW.OtOpcUa.Admin.E2ETests/`
+
+**Background:**
+Source plan Task 56 deleted the projects from `ZB.MOM.WW.OtOpcUa.slnx` (confirmed by the audit) but left `bin/`+`obj/` shells on disk. These confuse new contributors and skew directory listings. None of them are referenced anywhere.
+
+**Step 1: Sanity-check that each directory is bin/obj-only**
+
+```bash
+for dir in \
+  src/Server/ZB.MOM.WW.OtOpcUa.Server \
+  src/Server/ZB.MOM.WW.OtOpcUa.Admin \
+  tests/Server/ZB.MOM.WW.OtOpcUa.Server.Tests \
+  tests/Server/ZB.MOM.WW.OtOpcUa.Admin.Tests \
+  tests/Server/ZB.MOM.WW.OtOpcUa.Admin.E2ETests; do
+  echo "--- $dir ---"
+  find "$dir" -maxdepth 2 -type f | grep -v "/bin/\|/obj/"
+done
+```
+
+Expected: every section is empty (no source files leak out). If any source file shows, STOP and surface it — don't delete blindly.
+
+**Step 2: Verify slnx doesn't reference them**
+
+Run: `grep -nE 'ZB\.MOM\.WW\.OtOpcUa\.(Server|Admin)(/|\.Tests|\.E2ETests)' ZB.MOM.WW.OtOpcUa.slnx`
+Expected: zero matches.
+
+**Step 3: Delete the directories**
+
+```bash
+rm -rf src/Server/ZB.MOM.WW.OtOpcUa.Server \
+       src/Server/ZB.MOM.WW.OtOpcUa.Admin \
+       tests/Server/ZB.MOM.WW.OtOpcUa.Server.Tests \
+       tests/Server/ZB.MOM.WW.OtOpcUa.Admin.Tests \
+       tests/Server/ZB.MOM.WW.OtOpcUa.Admin.E2ETests
+```
+
+**Step 4: Build green check**
+
+Run: `dotnet build ZB.MOM.WW.OtOpcUa.slnx`
+Expected: succeeds (these directories were already out of the solution).
+
+**Step 5: Commit**
+
+```bash
+git add -A
+git commit -m "chore(cleanup): remove stale bin/obj shells for deleted v1 Server/Admin projects"
+```
+
+---
+
+## Task 7: Final build + test green check
+
+**Classification:** trivial
+**Estimated implement time:** ~3 min
+**Parallelizable with:** none (verification, depends on all prior tasks)
+
+**Step 1: Restore + build**
+
+Run: `dotnet build ZB.MOM.WW.OtOpcUa.slnx`
+Expected: 0 errors, 0 warnings (TreatWarningsAsErrors is on across the solution).
+
+**Step 2: Run the full test suite**
+
+Run: `dotnet test ZB.MOM.WW.OtOpcUa.slnx --no-build`
+Expected: all tests green. Specifically confirm:
+- `OpcUaApplicationHostServerArrayTests` (Task 1) — pass
+- `DualEndpointTests` (Task 3) — pass
+- `FailoverDuringDeployTests` (Task 5) — same count of tests pass as before the rename
+
+**Step 3: Smoke check the audit assertions**
+
+Run:
+```bash
+ls src/Server/ZB.MOM.WW.OtOpcUa.Host/appsettings.*.json
+find tests/Server -iname "DualEndpointTests.cs" -o -iname "FailoverDuringDeployTests.cs"
+ls -la src/Server/ZB.MOM.WW.OtOpcUa.{Server,Admin} 2>/dev/null
+```
+
+Expected:
+- 4 appsettings files: `.json`, `.Development.json`, `.admin.json`, `.admin-driver.json`, `.driver.json`
+- Both renamed/new test files exist
+- The two `ls -la` calls return errors (directories gone)
+
+**Step 4: No commit unless cleanup turned up**
+
+If anything failed in Steps 1-3, fix it as a follow-up task — do not paper over with a `--no-verify` commit.
+
+---
+
+## Final verification
+
+After Task 7:
+
+1. `dotnet build ZB.MOM.WW.OtOpcUa.slnx` — green
+2. `dotnet test ZB.MOM.WW.OtOpcUa.slnx --no-build` — green (incl. 2 new tests)
+3. `git log --oneline master..HEAD` — exactly 6 commits, Conventional-Commits style
+4. Open PR `v2-gap-closeout` → `master` titled "v2: close audit gaps — appsettings overlays, DualEndpointTests, cleanup"
+
+---
+
+## Task index
+
+| # | Title | Class | Time | Parallel with |
+|---|---|---|---|---|
+| 0 | Per-role appsettings overlays | small | 3m | 1, 5, 6 |
+| 1 | OpcUaApplicationHost.PeerApplicationUris + ServerArray | standard | 5m | 0, 5, 6 |
+| 2 | OpcUaServer.IntegrationTests project skeleton | small | 4m | 5, 6 |
+| 3 | DualEndpointTests | standard | 5m | 5, 6 |
+| 4 | CI matrix entry for new IT project | small | 3m | 5, 6 |
+| 5 | Rename FailoverScenarioTests → FailoverDuringDeployTests | trivial | 2m | 0, 1, 2, 6 |
+| 6 | Delete stale bin/obj-only directories | trivial | 2m | 0, 1, 2, 5 |
+| 7 | Final build + test green check | trivial | 3m | none |
+
+**Total estimated subagent time:** ~27 min.
+
+**Dependency graph (non-parallel pairs):**
+- Task 3 depends on Task 1 (option must exist) and Task 2 (project must exist)
+- Task 4 depends on Task 3 (CI runs the project's tests)
+- Task 7 depends on all prior tasks

docs/plans/2026-05-26-akka-hosting-alignment-gaps-closeout.md.tasks.json

@@ -0,0 +1,17 @@
+{
+  "planPath": "docs/plans/2026-05-26-akka-hosting-alignment-gaps-closeout.md",
+  "tasks": [
+    {"id": 1, "subject": "Task 0: Per-role appsettings overlays", "status": "completed", "commit": "898a477"},
+    {"id": 2, "subject": "Task 1: OpcUaApplicationHost.PeerApplicationUris + ServerArray population", "status": "completed", "commits": ["70ffd28", "cb936db"]},
+    {"id": 3, "subject": "Task 2: OpcUaServer.IntegrationTests project skeleton", "status": "completed", "commit": "83eda9e"},
+    {"id": 4, "subject": "Task 3: DualEndpointTests — real OPC UA client reads both URIs from Server.ServerArray", "status": "completed", "commits": ["dce2528", "a5412c1", "cb936db"], "blockedBy": ["2", "3"]},
+    {"id": 5, "subject": "Task 4: Wire OpcUaServer.IntegrationTests into v2-ci.yml", "status": "completed", "commit": "e8c4f18", "blockedBy": ["4"]},
+    {"id": 6, "subject": "Task 5: Rename FailoverScenarioTests → FailoverDuringDeployTests", "status": "completed", "commit": "25ce111"},
+    {"id": 7, "subject": "Task 6: Delete empty bin/obj-only legacy directories", "status": "completed", "commit": "(no tracked changes — bin/obj only)"},
+    {"id": 8, "subject": "Task 7: Final build + test green check", "status": "completed", "blockedBy": ["1", "2", "3", "4", "5", "6", "7"]}
+  ],
+  "lastUpdated": "2026-05-26T00:00:00Z",
+  "finalReview": "approved",
+  "branchHead": "e8c4f18",
+  "branchCommitCount": 8
+}

docs/security.md

@@ -109,7 +109,7 @@ The Server accepts three OPC UA identity-token types:
 | Token | Handler | Notes |
 |---|---|---|
 | Anonymous | `IUserAuthenticator.AuthenticateAsync(username: "", password: "")` | Refused in strict mode unless explicit anonymous grants exist; allowed in lax mode for backward compatibility. |
-| UserName/Password | `LdapUserAuthenticator` (`src/Server/ZB.MOM.WW.OtOpcUa.Server/Security/LdapUserAuthenticator.cs`) | LDAP bind + group lookup; resolved `LdapGroups` flow into the session's identity bearer (`ILdapGroupsBearer`). |
+| UserName/Password | `LdapOpcUaUserAuthenticator` (`src/Server/ZB.MOM.WW.OtOpcUa.Host/OpcUa/LdapOpcUaUserAuthenticator.cs`, backed by `LdapAuthService` at `src/Server/ZB.MOM.WW.OtOpcUa.Security/Ldap/LdapAuthService.cs`) | LDAP bind + group lookup; resolved `LdapGroups` flow into the session's identity bearer (`ILdapGroupsBearer`). |
 | X.509 Certificate | Stack-level acceptance + role mapping via CN | X.509 identity carries `AuthenticatedUser` + read roles; finer-grain authorization happens through the data-plane ACLs. |
 
 ### LDAP bind flow (`LdapUserAuthenticator`)
@@ -221,20 +221,16 @@ The three Write tiers map to Galaxy's v1 `SecurityClassification` — `FreeAcces
 
 `NodeScope` carries `(ClusterId, NamespaceId, AreaId, LineId, EquipmentId, TagId)`; any suffix may be null — a tag-level ACL is more specific than an area-level ACL but both contribute via union.
 
-### Dispatch gate — `AuthorizationGate`
+### Dispatch gate — `IPermissionEvaluator`
 
-`src/Server/ZB.MOM.WW.OtOpcUa.Server/Security/AuthorizationGate.cs` bridges the OPC UA stack's `ISystemContext.UserIdentity` to the evaluator. `DriverNodeManager` holds exactly one reference to it and calls `IsAllowed(identity, OpcUaOperation.*, NodeScope)` on every Read, Write, HistoryRead, Browse, Subscribe, AckAlarm, Call path. A false return short-circuits the dispatch with `BadUserAccessDenied`.
+`IPermissionEvaluator.Authorize(session, operation, scope)` (default impl `TriePermissionEvaluator` at `src/Core/ZB.MOM.WW.OtOpcUa.Core/Authorization/TriePermissionEvaluator.cs`) bridges the OPC UA stack's `ISystemContext.UserIdentity` to the trie. The dispatch path calls it on every Read, Write, HistoryRead, Browse, Subscribe, AckAlarm, Call. A non-allow decision short-circuits the dispatch with `BadUserAccessDenied`.
 
 Key properties:
 
-- **Driver-agnostic.** No driver-level code participates in authorization decisions. Drivers report `SecurityClassification` as metadata on tag discovery; everything else flows through `AuthorizationGate`.
+- **Driver-agnostic.** No driver-level code participates in authorization decisions. Drivers report `SecurityClassification` as metadata on tag discovery; everything else flows through the evaluator.
 - **Fail-open-during-transition.** `StrictMode = false` (default during ACL rollouts) lets sessions without resolved LDAP groups proceed; flip `Authorization:StrictMode = true` in production once ACLs are populated.
 - **Evaluator stays pure.** `TriePermissionEvaluator` has no OPC UA stack dependency — it's tested directly from xUnit.
 
-### Probe-this-permission (Admin UI)
-
-`PermissionProbeService` (`src/Server/ZB.MOM.WW.OtOpcUa.Admin/Services/PermissionProbeService.cs`) lets an operator ask "if a user with groups X, Y, Z asked to do operation O on node N, would it succeed?" The answer is rendered in the AclsTab "Probe" dialog — same evaluator, same trie, so the Admin UI answer and the live Server answer cannot disagree.
-
 ### Full model
 
 See [`docs/v2/acl-design.md`](v2/acl-design.md) for the complete design: trie invalidation, flag semantics, per-path override rules, and the reasoning behind additive-only (no Deny).
@@ -249,7 +245,7 @@ Per decision #150 control-plane roles are **deliberately independent of data-pla
 
 ### Roles
 
-`src/Server/ZB.MOM.WW.OtOpcUa.Admin/Services/AdminRoles.cs`:
+The `AdminRole` enum (`src/Core/ZB.MOM.WW.OtOpcUa.Configuration/Enums/AdminRole.cs`) defines:
 
 | Role | Capabilities |
 |---|---|
@@ -257,15 +253,7 @@ Per decision #150 control-plane roles are **deliberately independent of data-pla
 | `ConfigEditor` | ConfigViewer plus draft editing (UNS, equipment, tags, ACLs, driver instances, reservations, CSV imports). Cannot publish. |
 | `FleetAdmin` | ConfigEditor plus publish, cluster/node CRUD, credential management, role-grant management. |
 
-Policies registered in Admin `Program.cs`:
-
-```csharp
-builder.Services.AddAuthorizationBuilder()
-    .AddPolicy("CanEdit",    p => p.RequireRole(AdminRoles.ConfigEditor, AdminRoles.FleetAdmin))
-    .AddPolicy("CanPublish", p => p.RequireRole(AdminRoles.FleetAdmin));
-```
-
-Razor pages and API endpoints gate with `[Authorize(Policy = "CanEdit")]` / `"CanPublish"`; nav-menu sections hide via `<AuthorizeView>`.
+In v2 the authentication + authorization stack is wired centrally by `AddOtOpcUaAuth` (`src/Server/ZB.MOM.WW.OtOpcUa.Security/ServiceCollectionExtensions.cs`) and Razor pages gate inline with the role names, e.g. `@attribute [Authorize(Roles = "FleetAdmin,ConfigEditor")]` on `Deployments.razor`. Nav-menu sections hide via `<AuthorizeView>`.
 
 ### Role grant source
 

docs/v2/Architecture-v2.md

@@ -124,4 +124,5 @@ Each cluster member has a `NodeId` derived as `{PublicHostname}:{Port}` of the A
 | Driver actors | `Runtime.WithOtOpcUaRuntimeActors` | extension on `AkkaConfigurationBuilder` |
 | Auth pipeline | `Security.AddOtOpcUaAuth` + `MapOtOpcUaAuth` | extensions on `IServiceCollection` / `IEndpointRouteBuilder` |
 | OPC UA facade | `OpcUaServer.OpcUaApplicationHost` | runtime host, started by driver-role startup |
+| Partner-URI advertising | `OpcUaServer.OpcUaApplicationHost.PopulateServerArray` | runs after `_application.Start`, appends `PeerApplicationUris` to the SDK `ServerUris` `StringTable` so `Server.ServerArray` (i=2254) returns self + peers |
 | Health endpoints | `Host.Health.AddOtOpcUaHealth` + `MapOtOpcUaHealth` | extensions on `IServiceCollection` / `IEndpointRouteBuilder` |

docs/v2/Cluster.md

@@ -67,6 +67,8 @@ The Cluster.Tests project verifies these key values stay correct (`HoconLoaderTe
 - `SeedNodes`: where new nodes go to join. List one (or two) stable nodes. First node bootstraps the cluster from its own address.
 - `Roles`: free-form tags Akka gossip propagates. v2 uses `admin` + `driver`; per-role wiring in `Program.cs` reads `OTOPCUA_ROLES` env var, not this list — these two should stay in sync.
 
+Per-role overlay files (`appsettings.admin.json`, `appsettings.driver.json`, `appsettings.admin-driver.json`) layer on top of base `appsettings.json` based on the parsed `OTOPCUA_ROLES` (alphabetical, joined by `-`). See [ServiceHosting.md § Per-role configuration overlays](../ServiceHosting.md#per-role-configuration-overlays).
+
 ## IClusterRoleInfo
 
 Anywhere in the host that needs the local node's identity or a view of who-else-is-in-the-cluster, inject `IClusterRoleInfo`:

docs/v2/admin-ui.md

@@ -36,7 +36,7 @@ Mirror ScadaLink's layout exactly:
 
 ```
 src/
-  ZB.MOM.WW.OtOpcUa.Admin/                        # Razor Components project (.NET 10)
+  ZB.MOM.WW.OtOpcUa.AdminUI/                       # Razor Components project (.NET 10)
     Auth/
       AuthEndpoints.cs                            # /auth/login, /auth/logout, /auth/token
       CookieAuthenticationStateProvider.cs        # bridges cookie auth to Blazor <AuthorizeView>
@@ -61,10 +61,10 @@ src/
         NotAuthorizedView.razor
     EndpointExtensions.cs                         # MapAuthEndpoints + role policies
     ServiceCollectionExtensions.cs                # AddCentralAdmin
-  ZB.MOM.WW.OtOpcUa.Admin.Security/               # LDAP + role mapping + JWT (sibling of ScadaLink.Security)
+  ZB.MOM.WW.OtOpcUa.Security/                      # LDAP + role mapping + JWT (sibling of ScadaLink.Security)
 ```
 
-The `Admin.Security` project carries `LdapAuthService`, `RoleMapper`, `JwtTokenService`, `AuthorizationPolicies`. If it ever makes sense to consolidate with ScadaLink's identical project, lift to a shared internal NuGet — out of scope for v2.0 to keep OtOpcUa decoupled from ScadaLink's release cycle.
+The `Security` project carries `LdapAuthService`, `RoleMapper`, `JwtTokenService`, `AuthorizationPolicies`. If it ever makes sense to consolidate with ScadaLink's identical project, lift to a shared internal NuGet — out of scope for v2.0 to keep OtOpcUa decoupled from ScadaLink's release cycle.
 
 ## Authentication & Authorization
 

docs/v2/phase-7-status.md

@@ -96,7 +96,7 @@ Shipped as PR #183 (12 tests in configuration; 13 more in Admin.Tests).
 | F.4 — Test harness (modal, synthetic inputs, output + logger display) | **Partial** | `ScriptTestHarnessService.cs` is complete and tested. `ScriptsTab.razor` calls `Harness.RunVirtualTagAsync` with zero-value synthetic inputs derived from the extractor. A full interactive input-form modal was not shipped — the harness zeroes all inputs automatically rather than prompting the operator per-tag. |
 | F.5 — Script log viewer (SignalR tail of `scripts-*.log` filtered by `ScriptName`, load-more) | **Not started** | No SignalR stream of the scripts log is wired in the Admin UI. The `AlertHub` / `FleetStatusHub` exist but there is no `ScriptLogHub`. |
 | F.6 — `/alarms/historian` diagnostics view | **Done** | `AlarmsHistorian.razor` + `HistorianDiagnosticsService.cs` |
-| F.7 — Playwright smoke (author calc tag, verify in equipment tree; author alarm, verify in `AlarmsAndConditions`) | **Not started** | `tests/Server/ZB.MOM.WW.OtOpcUa.Admin.E2ETests/` exists but its `UnsTabDragDropE2ETests.cs` is the only Playwright test; no Phase 7 Admin UI playwright scenario. |
+| F.7 — Playwright smoke (author calc tag, verify in equipment tree; author alarm, verify in `AlarmsAndConditions`) | **Not started** | No Phase 7 Playwright/E2E project exists in the repo today; future-work item without an assigned path. |
 
 Shipped as PR #185 (13 Admin service tests; UI completeness is partial — see gaps section).
 
@@ -190,8 +190,8 @@ The SignalR tail of `scripts-*.log` filtered by `ScriptName` was not implemented
 | `Core.VirtualTags` sources | `src/Core/ZB.MOM.WW.OtOpcUa.Core.VirtualTags/` |
 | `Core.ScriptedAlarms` sources | `src/Core/ZB.MOM.WW.OtOpcUa.Core.ScriptedAlarms/` |
 | `Core.AlarmHistorian` sources | `src/Core/ZB.MOM.WW.OtOpcUa.Core.AlarmHistorian/` |
-| Server Phase7 composition | `src/Server/ZB.MOM.WW.OtOpcUa.Server/Phase7/` |
-| Admin services | `src/Server/ZB.MOM.WW.OtOpcUa.Admin/Services/Script*.cs`, `VirtualTagService.cs`, `HistorianDiagnosticsService.cs` |
-| Admin UI pages | `src/Server/ZB.MOM.WW.OtOpcUa.Admin/Components/Pages/Clusters/ScriptsTab.razor`, `AlarmsHistorian.razor` |
+| Server Phase7 composition | `src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/Phase7Composer.cs`, `Phase7Applier.cs`, `Phase7Plan.cs` |
+| Admin services (CRUD writes) | `src/Server/ZB.MOM.WW.OtOpcUa.ControlPlane/AdminOperations/AdminOperationsActor.cs` (actor-driven); live state in `src/Server/ZB.MOM.WW.OtOpcUa.Runtime/ScriptedAlarms/ScriptedAlarmActor.cs`, `Runtime/VirtualTags/VirtualTagActor.cs`; Roslyn engines in `src/Server/ZB.MOM.WW.OtOpcUa.Host/Engines/` — v1 `Admin/Services/Script*.cs`, `VirtualTagService.cs`, `HistorianDiagnosticsService.cs` deleted |
+| Admin UI pages | `src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Components/Pages/Scripts.razor`, `ScriptEdit.razor`, `ScriptedAlarms.razor`, `ScriptedAlarmEdit.razor`, `AlarmsHistorian.razor`, `VirtualTags.razor`, `VirtualTagEdit.razor` |
 | Historian sidecar writer | `src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.Wonderware.Client/WonderwareHistorianClient.cs` |
 | EF migrations | `src/Core/ZB.MOM.WW.OtOpcUa.Configuration/Migrations/20260420231641_AddPhase7ScriptingTables.cs`, `20260420232000_ExtendComputeGenerationDiffWithPhase7.cs` |

docs/v2/redundancy-interop-playbook.md

@@ -55,6 +55,7 @@ Each row is one manual run; pass criterion in the right column.
 | A2 | ServiceLevel updates on peer down | Connect to Primary. Stop Backup (`sc stop OtOpcUa`). Watch `ServiceLevel`. | Transitions 200 → 150 within ~2 s of peer probe timeout |
 | A3 | RedundancySupport | Browse to `Server.ServerRedundancy.RedundancySupport`. | Value matches the declared `RedundancyMode` (Warm / Hot / None) |
 | A4 | ServerUriArray (non-transparent upgrade) | Requires a redundancy-object-type upgrade follow-up. | When upgrade lands: `ServerUriArray` reports both ApplicationUris, self first |
+| A4b | Peer URI visibility via `Server.ServerArray` (i=2254) | Configure each `OpcUaApplicationHost` with the partner's `ApplicationUri` via `OpcUaApplicationHostOptions.PeerApplicationUris`. From any client, Read NodeId `i=2254` (`Server.ServerArray`). | Returned `String[]` includes both self + peer `ApplicationUri`s. Validated by `DualEndpointTests` in `tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.IntegrationTests/` (loopback dual-host with real OPCFoundation client `Session` read). |
 | A5 | Mid-apply dip | On Primary trigger a `sp_PublishGeneration` apply. | `ServiceLevel` drops to 75 for the apply duration + dwell |
 
 ### Block B — Client failover
@@ -101,7 +102,9 @@ flips A4 from "deferred" to "expected pass").
 - **A4 pending**: `Server.ServerRedundancy` on our current SDK build lands as
   the base `ServerRedundancyState`, which has no `ServerUriArray` child.
   `ServerRedundancyNodeWriter.ApplyServerUriArray` logs-and-skips until the
-  redundancy-object-type upgrade follow-up lands.
+  redundancy-object-type upgrade follow-up lands. Cross-reference **A4b** —
+  peer URIs are visible today via `Server.ServerArray` (i=2254) populated by
+  `OpcUaApplicationHost.PopulateServerArray`.
 - **Recovery dwell default**: `RecoveryStateManager.DwellTime` defaults to 60 s
   in `Program.cs`. Adjust via future config knob if B3 takes too long to
   observe.
@@ -121,8 +124,8 @@ flips A4 from "deferred" to "expected pass").
   redundancy implementations we don't control.
 - For the sub-set of scenarios that *can* be automated — the self-loopback
   case where our own `otopcua-cli` drives Primary + Backup — the existing
-  `tests/Server/ZB.MOM.WW.OtOpcUa.Server.Tests/RedundancyStatePublisherTests` +
-  `ServiceLevelCalculatorTests` (unit) + `ClusterTopologyLoaderTests`
-  (integration) already cover the math + data path. The wire-level assertion
-  that the values actually land on the right OPC UA nodes is covered by
-  `ServerRedundancyNodeWriterTests`.
+  `tests/Server/ZB.MOM.WW.OtOpcUa.ControlPlane.Tests/RedundancyStateActorTests` +
+  `ServiceLevelCalculatorTests` (unit) already cover the math + data path.
+  The wire-level assertion that the peer URIs actually land on the
+  `Server.ServerArray` node (i=2254) is covered by `DualEndpointTests` in
+  `tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.IntegrationTests/`.

docs/v2/v2-release-readiness.md

@@ -57,7 +57,7 @@ Remaining follow-ups (hardening):
 Remaining Phase 6.3 surfaces (hardening, not release-blocking):
 
 - ~~`PeerHttpProbeLoop` + `PeerUaProbeLoop` HostedServices populating `PeerReachabilityTracker` on each tick.~~ **Closed 2026-04-24.** Two-layer probe model shipped: HTTP probe at 2 s / 1 s timeout against `/healthz`; OPC UA probe at 10 s / 5 s timeout via `DiscoveryClient.GetEndpoints`, short-circuiting when HTTP reports the peer unhealthy. Registered on the Server as `AddHostedService<PeerHttpProbeLoop>` + `AddHostedService<PeerUaProbeLoop>`. Publisher now sees accurate `PeerReachability` per peer instead of degrading to `Unknown` → Isolated-Primary band (230).
-- OPC UA variable-node wiring: bind `ServiceLevel` Byte + `ServerUriArray` String[] to the publisher's events via `BaseDataVariable.OnReadValue` / direct value push.
+- ~~OPC UA variable-node wiring: bind `ServiceLevel` Byte + `ServerUriArray` String[] to the publisher's events via `BaseDataVariable.OnReadValue` / direct value push.~~ **Closed 2026-05-26.** `ServiceLevel` byte binding closed earlier under Path D. Peer-URI half closed via `OpcUaApplicationHost.PopulateServerArray` — populates self + each `PeerApplicationUris` entry into the SDK `IServerInternal.ServerUris` `StringTable`; clients read `Server.ServerArray` (NodeId `i=2254`). Validated by `DualEndpointTests` in `tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.IntegrationTests/`. `ServerUriArray` proper (the redundancy-object-type child) remains deferred pending object-type upgrade.
 - ~~`sp_PublishGeneration` wraps its apply in `await using var lease = coordinator.BeginApplyLease(...)` so the `PrimaryMidApply` band (200) fires during actual publishes (task #148 part 2).~~ **Closed 2026-04-24.** The apply loop now lives in `GenerationRefreshHostedService` — polls `sp_GetCurrentGenerationForCluster` every 5s, opens a lease when a new generation is detected, calls `RedundancyCoordinator.RefreshAsync` inside the `await using`, releases the lease on all exit paths. Replaces the previous "topology never refreshes without a process restart" behaviour.
 - Client interop matrix — Ignition / Kepware / Aveva OI Gateway (Stream F, task #150). Manual + doc-only.
 
@@ -118,6 +118,7 @@ v2 GA requires all of the following:
 
 ## Change log
 
+- **2026-05-26** — Gap-closeout pass. `OpcUaApplicationHost.PopulateServerArray` populates `Server.ServerArray` (NodeId `i=2254`) with self + `OpcUaApplicationHostOptions.PeerApplicationUris`, giving non-transparent peer URI visibility through the standard discovery surface. New `tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.IntegrationTests/` IT project (`DualEndpointTests`) validates with two real `OpcUaApplicationHost` instances on loopback + a live OPCFoundation client `Session` read. CI `v2-ci.yml` `integration:` job converted to a matrix across `Host.IntegrationTests` + `OpcUaServer.IntegrationTests`. Per-role appsettings overlays shipped (`appsettings.admin.json` / `appsettings.driver.json` / `appsettings.admin-driver.json`) — `Program.cs:33-35` loads by alphabetical-joined role suffix. `FailoverScenarioTests` → `FailoverDuringDeployTests` rename. Stale empty `src/Server/{Server,Admin}` + `tests/Server/{Server.Tests,Admin.Tests,Admin.E2ETests}` directories deleted (no source, absent from `.slnx`).
 - **2026-04-24** — Phase 5 driver complement closed (task #120 CLOSED). AB CIP, AB Legacy, TwinCAT, FOCAS all shipped. FOCAS migration: retired the Tier-C split (`Driver.FOCAS.Host` + `Driver.FOCAS.Shared` + `FwlibNative` + shim DLL deleted) in favour of a pure-managed in-process `FocasWireClient` inlined into `Driver.FOCAS`; driver is now read-only against the CNC by design. Integration test matrix grew to cover Browse / Subscribe / IAlarmSource / Probe end-to-end.
 - **2026-04-23** — Phase 6.4 audit close-out. IdentificationFolderBuilder + OPC 40010 Identification folder verified against the shipped code.
 - **2026-04-20** — Phase 7 plan drafted (`phase-7-scripting-and-alarming.md`, `phase-7-e2e-smoke.md`). Out of scope for v2 GA.

src/Client/ZB.MOM.WW.OtOpcUa.Client.CLI/Commands/AlarmsCommand.cs

@@ -42,6 +42,7 @@ public class AlarmsCommand : CommandBase
     /// Connects to the server, subscribes to alarm events, and streams operator-facing alarm state changes to the console.
     /// </summary>
     /// <param name="console">The CLI console used for output and cancellation handling.</param>
+    /// <inheritdoc />
     public override async ValueTask ExecuteAsync(IConsole console)
     {
         ConfigureLogging();

src/Client/ZB.MOM.WW.OtOpcUa.Client.CLI/Commands/BrowseCommand.cs

@@ -36,10 +36,7 @@ public class BrowseCommand : CommandBase
     [CommandOption("recursive", 'r', Description = "Browse recursively (uses --depth as max depth)")]
     public bool Recursive { get; init; }
 
-    /// <summary>
-    /// Connects to the server and prints a tree view of the requested address-space branch.
-    /// </summary>
-    /// <param name="console">The CLI console used for output and cancellation handling.</param>
+    /// <inheritdoc />
     public override async ValueTask ExecuteAsync(IConsole console)
     {
         ConfigureLogging();

src/Client/ZB.MOM.WW.OtOpcUa.Client.CLI/Commands/ConnectCommand.cs

@@ -15,10 +15,7 @@ public class ConnectCommand : CommandBase
     {
     }
 
-    /// <summary>
-    /// Connects to the server and prints the negotiated endpoint details for operator verification.
-    /// </summary>
-    /// <param name="console">The CLI console used for output and cancellation handling.</param>
+    /// <inheritdoc />
     public override async ValueTask ExecuteAsync(IConsole console)
     {
         ConfigureLogging();

src/Client/ZB.MOM.WW.OtOpcUa.Client.CLI/Commands/HistoryReadCommand.cs

@@ -56,10 +56,7 @@ public class HistoryReadCommand : CommandBase
     [CommandOption("interval", Description = "Processing interval in milliseconds for aggregates")]
     public double IntervalMs { get; init; } = 3600000;
 
-    /// <summary>
-    /// Connects to the server and prints raw or processed historical values for the requested node.
-    /// </summary>
-    /// <param name="console">The CLI console used for output and cancellation handling.</param>
+    /// <inheritdoc />
     public override async ValueTask ExecuteAsync(IConsole console)
     {
         ConfigureLogging();

src/Client/ZB.MOM.WW.OtOpcUa.Client.CLI/Commands/ReadCommand.cs

@@ -24,10 +24,7 @@ public class ReadCommand : CommandBase
     [CommandOption("node", 'n', Description = "Node ID (e.g. ns=2;s=MyNode)", IsRequired = true)]
     public string NodeId { get; init; } = default!;
 
-    /// <summary>
-    /// Connects to the server and prints the current value, status, and timestamps for the requested node.
-    /// </summary>
-    /// <param name="console">The CLI console used for output and cancellation handling.</param>
+    /// <inheritdoc />
     public override async ValueTask ExecuteAsync(IConsole console)
     {
         ConfigureLogging();

src/Client/ZB.MOM.WW.OtOpcUa.Client.CLI/Commands/RedundancyCommand.cs

@@ -15,10 +15,8 @@ public class RedundancyCommand : CommandBase
     {
     }
 
-    /// <summary>
-    /// Connects to the server and prints redundancy mode, service level, and partner-server identity data.
-    /// </summary>
-    /// <param name="console">The CLI console used for output and cancellation handling.</param>
+    /// <summary>Connects to the server and prints redundancy mode, service level, and partner-server identity data.</summary>
+    /// <inheritdoc />
     public override async ValueTask ExecuteAsync(IConsole console)
     {
         ConfigureLogging();

src/Client/ZB.MOM.WW.OtOpcUa.Client.CLI/Commands/SubscribeCommand.cs

@@ -67,11 +67,7 @@ public class SubscribeCommand : CommandBase
     [CommandOption("summary-file", Description = "Write summary to this file path on exit (in addition to stdout)")]
     public string? SummaryFile { get; init; }
 
-    /// <summary>
-    /// Connects to the server, subscribes to <see cref="NodeId" /> (or its subtree when recursive),
-    /// streams data-change notifications to the console, and prints a summary when the command exits.
-    /// </summary>
-    /// <param name="console">The CLI console used for output and cancellation handling.</param>
+    /// <inheritdoc />
     public override async ValueTask ExecuteAsync(IConsole console)
     {
         ConfigureLogging();

src/Client/ZB.MOM.WW.OtOpcUa.Client.CLI/Commands/WriteCommand.cs

@@ -35,6 +35,7 @@ public class WriteCommand : CommandBase
     /// Connects to the server, converts the supplied value to the node's current data type, and issues the write.
     /// </summary>
     /// <param name="console">The CLI console used for output and cancellation handling.</param>
+    /// <inheritdoc />
     public override async ValueTask ExecuteAsync(IConsole console)
     {
         ConfigureLogging();

src/Client/ZB.MOM.WW.OtOpcUa.Client.Shared/Adapters/DefaultApplicationConfigurationFactory.cs

@@ -12,6 +12,9 @@ internal sealed class DefaultApplicationConfigurationFactory : IApplicationConfi
 {
     private static readonly ILogger Logger = Log.ForContext<DefaultApplicationConfigurationFactory>();
 
+    /// <summary>Creates an OPC UA application configuration from the provided connection settings.</summary>
+    /// <param name="settings">The connection settings to use.</param>
+    /// <param name="ct">Token to cancel the operation.</param>
     public async Task<ApplicationConfiguration> CreateAsync(ConnectionSettings settings, CancellationToken ct)
     {
         // Resolve the canonical PKI path lazily on first use so constructing a

src/Client/ZB.MOM.WW.OtOpcUa.Client.Shared/Adapters/DefaultEndpointDiscovery.cs

@@ -11,6 +11,10 @@ internal sealed class DefaultEndpointDiscovery : IEndpointDiscovery
 {
     private static readonly ILogger Logger = Log.ForContext<DefaultEndpointDiscovery>();
 
+    /// <summary>Selects an OPC UA endpoint matching the requested security mode.</summary>
+    /// <param name="config">The application configuration.</param>
+    /// <param name="endpointUrl">The endpoint URL to query.</param>
+    /// <param name="requestedMode">The requested message security mode.</param>
     public EndpointDescription SelectEndpoint(ApplicationConfiguration config, string endpointUrl,
         MessageSecurityMode requestedMode)
     {

src/Client/ZB.MOM.WW.OtOpcUa.Client.Shared/Adapters/DefaultSessionFactory.cs

@@ -11,6 +11,14 @@ internal sealed class DefaultSessionFactory : ISessionFactory
 {
     private static readonly ILogger Logger = Log.ForContext<DefaultSessionFactory>();
 
+    /// <summary>Creates a new OPC UA session.</summary>
+    /// <param name="config">The OPC UA application configuration.</param>
+    /// <param name="endpoint">The endpoint description to connect to.</param>
+    /// <param name="sessionName">The name for the session.</param>
+    /// <param name="sessionTimeoutMs">The session timeout in milliseconds.</param>
+    /// <param name="identity">The user identity for the session.</param>
+    /// <param name="ct">The cancellation token.</param>
+    /// <returns>An adapter wrapping the created session.</returns>
     public async Task<ISessionAdapter> CreateSessionAsync(
         ApplicationConfiguration config,
         EndpointDescription endpoint,

src/Client/ZB.MOM.WW.OtOpcUa.Client.Shared/Adapters/IApplicationConfigurationFactory.cs

@@ -11,5 +11,7 @@ internal interface IApplicationConfigurationFactory
     /// <summary>
     ///     Creates a validated ApplicationConfiguration for the given connection settings.
     /// </summary>
+    /// <param name="settings">The connection settings to configure.</param>
+    /// <param name="ct">Cancellation token for the operation.</param>
     Task<ApplicationConfiguration> CreateAsync(ConnectionSettings settings, CancellationToken ct = default);
 }

src/Client/ZB.MOM.WW.OtOpcUa.Client.Shared/Adapters/IEndpointDiscovery.cs

@@ -11,6 +11,9 @@ internal interface IEndpointDiscovery
     ///     Discovers endpoints at the given URL and returns the best match for the requested security mode.
     ///     Also rewrites the endpoint URL hostname to match the requested URL when they differ.
     /// </summary>
+    /// <param name="config">The OPC UA application configuration.</param>
+    /// <param name="endpointUrl">The endpoint URL to discover.</param>
+    /// <param name="requestedMode">The requested message security mode.</param>
     EndpointDescription SelectEndpoint(ApplicationConfiguration config, string endpointUrl,
         MessageSecurityMode requestedMode);
 }

src/Client/ZB.MOM.WW.OtOpcUa.Client.Shared/Helpers/AggregateTypeMapper.cs

@@ -11,6 +11,8 @@ public static class AggregateTypeMapper
     /// <summary>
     ///     Returns the OPC UA NodeId for the specified aggregate type.
     /// </summary>
+    /// <param name="aggregate">The aggregate type to map to a NodeId.</param>
+    /// <returns>The OPC UA NodeId for the aggregate function.</returns>
     public static NodeId ToNodeId(AggregateType aggregate)
     {
         return aggregate switch

src/Client/ZB.MOM.WW.OtOpcUa.Client.Shared/Helpers/SecurityModeMapper.cs

@@ -8,9 +8,9 @@ namespace ZB.MOM.WW.OtOpcUa.Client.Shared.Helpers;
 /// </summary>
 public static class SecurityModeMapper
 {
-    /// <summary>
-    ///     Converts a <see cref="SecurityMode" /> to an OPC UA <see cref="MessageSecurityMode" />.
-    /// </summary>
+    /// <summary>Converts a SecurityMode to an OPC UA MessageSecurityMode.</summary>
+    /// <param name="mode">The security mode to convert.</param>
+    /// <returns>The corresponding message security mode.</returns>
     public static MessageSecurityMode ToMessageSecurityMode(SecurityMode mode)
     {
         return mode switch

src/Client/ZB.MOM.WW.OtOpcUa.Client.Shared/IOpcUaClientServiceFactory.cs

@@ -5,5 +5,7 @@ namespace ZB.MOM.WW.OtOpcUa.Client.Shared;
 /// </summary>
 public interface IOpcUaClientServiceFactory
 {
+    /// <summary>Creates a new OPC UA client service instance.</summary>
+    /// <returns>A new <see cref="IOpcUaClientService"/> instance.</returns>
     IOpcUaClientService Create();
 }

src/Client/ZB.MOM.WW.OtOpcUa.Client.Shared/Models/AlarmEventArgs.cs

@@ -5,6 +5,20 @@ namespace ZB.MOM.WW.OtOpcUa.Client.Shared.Models;
 /// </summary>
 public sealed class AlarmEventArgs : EventArgs
 {
+    /// <summary>Initializes a new instance of the <see cref="AlarmEventArgs"/> class.</summary>
+    /// <param name="sourceName">The name of the source object that raised the alarm.</param>
+    /// <param name="conditionName">The condition type name.</param>
+    /// <param name="severity">The alarm severity (0-1000).</param>
+    /// <param name="message">Human-readable alarm message.</param>
+    /// <param name="retain">Whether the alarm should be retained in the display.</param>
+    /// <param name="activeState">Whether the alarm condition is currently active.</param>
+    /// <param name="ackedState">Whether the alarm has been acknowledged.</param>
+    /// <param name="time">The time the event occurred.</param>
+    /// <param name="eventId">The EventId used for alarm acknowledgment.</param>
+    /// <param name="conditionNodeId">The NodeId of the condition instance.</param>
+    /// <param name="operatorComment">Operator-supplied comment on acknowledgment transitions.</param>
+    /// <param name="originalRaiseTimestampUtc">When the alarm originally entered the active state.</param>
+    /// <param name="alarmCategory">Upstream alarm taxonomy bucket (e.g. Process, Safety, Diagnostics).</param>
     public AlarmEventArgs(
         string sourceName,
         string conditionName,

src/Client/ZB.MOM.WW.OtOpcUa.Client.Shared/Models/BrowseResult.cs

@@ -5,6 +5,11 @@ namespace ZB.MOM.WW.OtOpcUa.Client.Shared.Models;
 /// </summary>
 public sealed class BrowseResult
 {
+    /// <summary>Initializes a new instance of the BrowseResult class.</summary>
+    /// <param name="nodeId">The string representation of the node's NodeId.</param>
+    /// <param name="displayName">The display name of the node.</param>
+    /// <param name="nodeClass">The node class (e.g., "Object", "Variable", "Method").</param>
+    /// <param name="hasChildren">Whether the node has child references.</param>
     public BrowseResult(string nodeId, string displayName, string nodeClass, bool hasChildren)
     {
         NodeId = nodeId;

src/Client/ZB.MOM.WW.OtOpcUa.Client.Shared/Models/ConnectionInfo.cs

@@ -5,6 +5,13 @@ namespace ZB.MOM.WW.OtOpcUa.Client.Shared.Models;
 /// </summary>
 public sealed class ConnectionInfo
 {
+    /// <summary>Initializes a new instance of the ConnectionInfo with session details.</summary>
+    /// <param name="endpointUrl">The endpoint URL of the connected server.</param>
+    /// <param name="serverName">The server application name.</param>
+    /// <param name="securityMode">The security mode in use.</param>
+    /// <param name="securityPolicyUri">The security policy URI.</param>
+    /// <param name="sessionId">The session identifier.</param>
+    /// <param name="sessionName">The session name.</param>
     public ConnectionInfo(
         string endpointUrl,
         string serverName,

src/Client/ZB.MOM.WW.OtOpcUa.Client.Shared/Models/ConnectionStateChangedEventArgs.cs

@@ -5,6 +5,10 @@ namespace ZB.MOM.WW.OtOpcUa.Client.Shared.Models;
 /// </summary>
 public sealed class ConnectionStateChangedEventArgs : EventArgs
 {
+    /// <summary>Initializes a new instance of the ConnectionStateChangedEventArgs class.</summary>
+    /// <param name="oldState">The previous connection state.</param>
+    /// <param name="newState">The new connection state.</param>
+    /// <param name="endpointUrl">The endpoint URL associated with the state change.</param>
     public ConnectionStateChangedEventArgs(ConnectionState oldState, ConnectionState newState, string endpointUrl)
     {
         OldState = oldState;

src/Client/ZB.MOM.WW.OtOpcUa.Client.Shared/Models/DataChangedEventArgs.cs

@@ -7,6 +7,9 @@ namespace ZB.MOM.WW.OtOpcUa.Client.Shared.Models;
 /// </summary>
 public sealed class DataChangedEventArgs : EventArgs
 {
+    /// <summary>Initializes a new instance of the DataChangedEventArgs class.</summary>
+    /// <param name="nodeId">The node ID that changed.</param>
+    /// <param name="value">The new data value.</param>
     public DataChangedEventArgs(string nodeId, DataValue value)
     {
         NodeId = nodeId;

src/Client/ZB.MOM.WW.OtOpcUa.Client.Shared/Models/RedundancyInfo.cs

@@ -5,6 +5,11 @@ namespace ZB.MOM.WW.OtOpcUa.Client.Shared.Models;
 /// </summary>
 public sealed class RedundancyInfo
 {
+    /// <summary>Initializes a new instance of the RedundancyInfo class.</summary>
+    /// <param name="mode">The redundancy mode (e.g., "None", "Cold", "Warm", "Hot").</param>
+    /// <param name="serviceLevel">The server's current service level (0-255).</param>
+    /// <param name="serverUris">URIs of all servers in the redundant set.</param>
+    /// <param name="applicationUri">The application URI of the connected server.</param>
     public RedundancyInfo(string mode, byte serviceLevel, string[] serverUris, string applicationUri)
     {
         Mode = mode;

src/Client/ZB.MOM.WW.OtOpcUa.Client.Shared/OpcUaClientServiceFactory.cs

@@ -5,6 +5,8 @@ namespace ZB.MOM.WW.OtOpcUa.Client.Shared;
 /// </summary>
 public sealed class OpcUaClientServiceFactory : IOpcUaClientServiceFactory
 {
+    /// <summary>Creates a new OPC UA client service instance with production adapters.</summary>
+    /// <returns>A new OpcUaClientService instance.</returns>
     public IOpcUaClientService Create()
     {
         return new OpcUaClientService();

src/Client/ZB.MOM.WW.OtOpcUa.Client.UI/App.axaml.cs

@@ -10,11 +10,13 @@ namespace ZB.MOM.WW.OtOpcUa.Client.UI;
 
 public class App : Application
 {
+    /// <inheritdoc />
     public override void Initialize()
     {
         AvaloniaXamlLoader.Load(this);
     }
 
+    /// <inheritdoc />
     public override void OnFrameworkInitializationCompleted()
     {
         if (ApplicationLifetime is IClassicDesktopStyleApplicationLifetime desktop)

src/Client/ZB.MOM.WW.OtOpcUa.Client.UI/Controls/DateTimeRangePicker.axaml.cs

@@ -32,35 +32,41 @@ public partial class DateTimeRangePicker : UserControl
 
     private bool _isUpdating;
 
+    /// <summary>Initializes a new instance of the <see cref="DateTimeRangePicker"/> class.</summary>
     public DateTimeRangePicker()
     {
         InitializeComponent();
     }
 
+    /// <summary>Gets or sets the start date and time.</summary>
     public DateTimeOffset? StartDateTime
     {
         get => GetValue(StartDateTimeProperty);
         set => SetValue(StartDateTimeProperty, value);
     }
 
+    /// <summary>Gets or sets the end date and time.</summary>
     public DateTimeOffset? EndDateTime
     {
         get => GetValue(EndDateTimeProperty);
         set => SetValue(EndDateTimeProperty, value);
     }
 
+    /// <summary>Gets or sets the start date/time as formatted text.</summary>
     public string StartText
     {
         get => GetValue(StartTextProperty);
         set => SetValue(StartTextProperty, value);
     }
 
+    /// <summary>Gets or sets the end date/time as formatted text.</summary>
     public string EndText
     {
         get => GetValue(EndTextProperty);
         set => SetValue(EndTextProperty, value);
     }
 
+    /// <inheritdoc />
     protected override void OnLoaded(RoutedEventArgs e)
     {
         base.OnLoaded(e);
@@ -82,6 +88,7 @@ public partial class DateTimeRangePicker : UserControl
         if (lastWeek != null) lastWeek.Click += (_, _) => ApplyPreset(TimeSpan.FromDays(7));
     }
 
+    /// <inheritdoc />
     protected override void OnPropertyChanged(AvaloniaPropertyChangedEventArgs change)
     {
         base.OnPropertyChanged(change);

src/Client/ZB.MOM.WW.OtOpcUa.Client.UI/Helpers/StatusCodeFormatter.cs

@@ -7,6 +7,9 @@ namespace ZB.MOM.WW.OtOpcUa.Client.UI.Helpers;
 /// </summary>
 internal static class StatusCodeFormatter
 {
+    /// <summary>Formats an OPC UA status code as a hexadecimal code with description.</summary>
+    /// <param name="statusCode">The OPC UA status code to format.</param>
+    /// <returns>A formatted string in the form "0xHEX (description)".</returns>
     public static string Format(StatusCode statusCode)
     {
         var code = statusCode.Code;

src/Client/ZB.MOM.WW.OtOpcUa.Client.UI/Helpers/ValueFormatter.cs

@@ -7,6 +7,9 @@ namespace ZB.MOM.WW.OtOpcUa.Client.UI.Helpers;
 /// </summary>
 internal static class ValueFormatter
 {
+    /// <summary>Formats an OPC UA value for display, handling arrays and enumerables specially.</summary>
+    /// <param name="value">The value to format, or null.</param>
+    /// <returns>A string representation of the value suitable for display.</returns>
     public static string Format(object? value)
     {
         if (value is null) return "(null)";

src/Client/ZB.MOM.WW.OtOpcUa.Client.UI/Program.cs

@@ -4,8 +4,11 @@ using ZB.MOM.WW.OtOpcUa.Client.Shared;
 
 namespace ZB.MOM.WW.OtOpcUa.Client.UI;
 
+/// <summary>Entry point for the OPC UA client UI application.</summary>
 public class Program
 {
+    /// <summary>Main entry point for the application.</summary>
+    /// <param name="args">Command-line arguments passed to the application.</param>
     [STAThread]
     public static void Main(string[] args)
     {
@@ -21,6 +24,8 @@ public class Program
         }
     }
 
+    /// <summary>Builds the Avalonia AppBuilder with platform-specific configuration.</summary>
+    /// <returns>Configured AppBuilder for desktop lifetime.</returns>
     public static AppBuilder BuildAvaloniaApp()
     {
         return AppBuilder.Configure<App>()

src/Client/ZB.MOM.WW.OtOpcUa.Client.UI/Services/AvaloniaUiDispatcher.cs

@@ -7,6 +7,8 @@ namespace ZB.MOM.WW.OtOpcUa.Client.UI.Services;
 /// </summary>
 public sealed class AvaloniaUiDispatcher : IUiDispatcher
 {
+    /// <summary>Posts an action to the Avalonia UI thread for execution.</summary>
+    /// <param name="action">The action to execute on the UI thread.</param>
     public void Post(Action action)
     {
         Dispatcher.UIThread.Post(action);

src/Client/ZB.MOM.WW.OtOpcUa.Client.UI/Services/ISettingsService.cs

@@ -5,6 +5,9 @@ namespace ZB.MOM.WW.OtOpcUa.Client.UI.Services;
 /// </summary>
 public interface ISettingsService
 {
+    /// <summary>Loads user settings from persistent storage.</summary>
     UserSettings Load();
+    /// <summary>Saves user settings to persistent storage.</summary>
+    /// <param name="settings">The settings to save.</param>
     void Save(UserSettings settings);
 }

src/Client/ZB.MOM.WW.OtOpcUa.Client.UI/Services/IUiDispatcher.cs

@@ -8,5 +8,6 @@ public interface IUiDispatcher
     /// <summary>
     ///     Posts an action to be executed on the UI thread.
     /// </summary>
+    /// <param name="action">The action to execute on the UI thread.</param>
     void Post(Action action);
 }

src/Client/ZB.MOM.WW.OtOpcUa.Client.UI/Services/JsonSettingsService.cs

@@ -19,6 +19,8 @@ public sealed class JsonSettingsService : ISettingsService
         WriteIndented = true
     };
 
+    /// <summary>Loads user settings from the settings file.</summary>
+    /// <returns>The loaded user settings, or a new default instance if load fails.</returns>
     public UserSettings Load()
     {
         try
@@ -35,6 +37,8 @@ public sealed class JsonSettingsService : ISettingsService
         }
     }
 
+    /// <summary>Saves user settings to the settings file.</summary>
+    /// <param name="settings">The user settings to save.</param>
     public void Save(UserSettings settings)
     {
         try

src/Client/ZB.MOM.WW.OtOpcUa.Client.UI/Services/SynchronousUiDispatcher.cs

@@ -6,6 +6,8 @@ namespace ZB.MOM.WW.OtOpcUa.Client.UI.Services;
 /// </summary>
 public sealed class SynchronousUiDispatcher : IUiDispatcher
 {
+    /// <summary>Executes the action synchronously on the calling thread.</summary>
+    /// <param name="action">The action to execute.</param>
     public void Post(Action action)
     {
         action();

src/Client/ZB.MOM.WW.OtOpcUa.Client.UI/ViewModels/AlarmsViewModel.cs

@@ -44,6 +44,9 @@ public partial class AlarmsViewModel : ObservableObject
 
     [ObservableProperty] private int _activeAlarmCount;
 
+    /// <summary>Initializes a new instance of the AlarmsViewModel class.</summary>
+    /// <param name="service">The OPC UA client service.</param>
+    /// <param name="dispatcher">The UI dispatcher for thread-safe operations.</param>
     public AlarmsViewModel(IOpcUaClientService service, IUiDispatcher dispatcher)
     {
         _service = service;
@@ -168,6 +171,9 @@ public partial class AlarmsViewModel : ObservableObject
     /// <summary>
     ///     Acknowledges an alarm and returns (success, message).
     /// </summary>
+    /// <param name="alarm">The alarm event to acknowledge.</param>
+    /// <param name="comment">Optional comment for the acknowledgment.</param>
+    /// <returns>A tuple with success flag and message.</returns>
     public async Task<(bool Success, string Message)> AcknowledgeAlarmAsync(AlarmEventViewModel alarm, string comment)
     {
         if (!IsConnected || alarm.EventId == null || alarm.ConditionNodeId == null)
@@ -197,6 +203,8 @@ public partial class AlarmsViewModel : ObservableObject
     /// <summary>
     ///     Restores an alarm subscription and requests a condition refresh.
     /// </summary>
+    /// <param name="sourceNodeId">The source node ID to restore the subscription for.</param>
+    /// <returns>A task that completes when the restore operation finishes.</returns>
     public async Task RestoreAlarmSubscriptionAsync(string? sourceNodeId)
     {
         if (!IsConnected || string.IsNullOrWhiteSpace(sourceNodeId)) return;

src/Client/ZB.MOM.WW.OtOpcUa.Client.UI/ViewModels/BrowseTreeViewModel.cs

@@ -13,6 +13,11 @@ public class BrowseTreeViewModel : ObservableObject
     private readonly IUiDispatcher _dispatcher;
     private readonly IOpcUaClientService _service;
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="BrowseTreeViewModel"/> class.
+    /// </summary>
+    /// <param name="service">The OPC UA client service.</param>
+    /// <param name="dispatcher">The UI dispatcher for marshaling updates.</param>
     public BrowseTreeViewModel(IOpcUaClientService service, IUiDispatcher dispatcher)
     {
         _service = service;

src/Client/ZB.MOM.WW.OtOpcUa.Client.UI/ViewModels/HistoryValueViewModel.cs

@@ -7,6 +7,11 @@ namespace ZB.MOM.WW.OtOpcUa.Client.UI.ViewModels;
 /// </summary>
 public class HistoryValueViewModel : ObservableObject
 {
+    /// <summary>Initializes a new instance of the <see cref="HistoryValueViewModel"/> class.</summary>
+    /// <param name="value">The historical value.</param>
+    /// <param name="status">The status code or text.</param>
+    /// <param name="sourceTimestamp">The source timestamp in string format.</param>
+    /// <param name="serverTimestamp">The server timestamp in string format.</param>
     public HistoryValueViewModel(string value, string status, string sourceTimestamp, string serverTimestamp)
     {
         Value = value;
@@ -15,8 +20,12 @@ public class HistoryValueViewModel : ObservableObject
         ServerTimestamp = serverTimestamp;
     }
 
+    /// <summary>Gets the historical value.</summary>
     public string Value { get; }
+    /// <summary>Gets the status code or text.</summary>
     public string Status { get; }
+    /// <summary>Gets the source timestamp in string format.</summary>
     public string SourceTimestamp { get; }
+    /// <summary>Gets the server timestamp in string format.</summary>
     public string ServerTimestamp { get; }
 }

src/Client/ZB.MOM.WW.OtOpcUa.Client.UI/ViewModels/HistoryViewModel.cs

@@ -34,6 +34,9 @@ public partial class HistoryViewModel : ObservableObject
 
     [ObservableProperty] private DateTimeOffset? _startTime = DateTimeOffset.UtcNow.AddHours(-1);
 
+    /// <summary>Initializes a new instance of the HistoryViewModel.</summary>
+    /// <param name="service">The OPC UA client service.</param>
+    /// <param name="dispatcher">The UI dispatcher for thread marshalling.</param>
     public HistoryViewModel(IOpcUaClientService service, IUiDispatcher dispatcher)
     {
         _service = service;
@@ -53,6 +56,7 @@ public partial class HistoryViewModel : ObservableObject
         AggregateType.StandardDeviation
     ];
 
+    /// <summary>Gets a value indicating whether an aggregate read is selected.</summary>
     public bool IsAggregateRead => SelectedAggregateType != null;
 
     /// <summary>History read results.</summary>

src/Client/ZB.MOM.WW.OtOpcUa.Client.UI/ViewModels/ReadWriteViewModel.cs

@@ -36,12 +36,16 @@ public partial class ReadWriteViewModel : ObservableObject
 
     [ObservableProperty] private string? _writeValue;
 
+    /// <summary>Initializes a new instance of the ReadWriteViewModel class.</summary>
+    /// <param name="service">The OPC UA client service for read/write operations.</param>
+    /// <param name="dispatcher">The UI dispatcher for posting updates to the UI thread.</param>
     public ReadWriteViewModel(IOpcUaClientService service, IUiDispatcher dispatcher)
     {
         _service = service;
         _dispatcher = dispatcher;
     }
 
+    /// <summary>Gets a value indicating whether a node is currently selected.</summary>
     public bool IsNodeSelected => !string.IsNullOrEmpty(SelectedNodeId);
 
     partial void OnSelectedNodeIdChanged(string? value)

src/Client/ZB.MOM.WW.OtOpcUa.Client.UI/ViewModels/SubscriptionItemViewModel.cs

@@ -13,6 +13,9 @@ public partial class SubscriptionItemViewModel : ObservableObject
 
     [ObservableProperty] private string? _value;
 
+    /// <summary>Initializes a new subscription item with the specified node ID and interval.</summary>
+    /// <param name="nodeId">The OPC UA NodeId to subscribe to.</param>
+    /// <param name="intervalMs">The subscription interval in milliseconds.</param>
     public SubscriptionItemViewModel(string nodeId, int intervalMs)
     {
         NodeId = nodeId;

src/Client/ZB.MOM.WW.OtOpcUa.Client.UI/ViewModels/TreeNodeViewModel.cs

@@ -31,6 +31,13 @@ public partial class TreeNodeViewModel : ObservableObject
         HasChildren = false;
     }
 
+    /// <summary>Initializes a new tree node view model.</summary>
+    /// <param name="nodeId">The OPC UA node identifier.</param>
+    /// <param name="displayName">The display name for this node.</param>
+    /// <param name="nodeClass">The OPC UA node class.</param>
+    /// <param name="hasChildren">Whether this node has child nodes.</param>
+    /// <param name="service">The OPC UA client service for browsing.</param>
+    /// <param name="dispatcher">The UI dispatcher for thread-safe updates.</param>
     public TreeNodeViewModel(
         string nodeId,
         string displayName,

src/Client/ZB.MOM.WW.OtOpcUa.Client.UI/Views/AckAlarmWindow.axaml.cs

@@ -10,6 +10,7 @@ public partial class AckAlarmWindow : Window
     private readonly AlarmsViewModel _alarmsVm;
     private readonly AlarmEventViewModel _alarm;
 
+    /// <summary>Initializes a new instance of the AckAlarmWindow class for XAML designer support.</summary>
     public AckAlarmWindow()
     {
         InitializeComponent();
@@ -17,6 +18,9 @@ public partial class AckAlarmWindow : Window
         _alarm = null!;
     }
 
+    /// <summary>Initializes a new instance of the AckAlarmWindow class with alarm context.</summary>
+    /// <param name="alarmsVm">The alarms view model.</param>
+    /// <param name="alarm">The alarm event to acknowledge.</param>
     public AckAlarmWindow(AlarmsViewModel alarmsVm, AlarmEventViewModel alarm)
     {
         InitializeComponent();

src/Client/ZB.MOM.WW.OtOpcUa.Client.UI/Views/AlarmsView.axaml.cs

@@ -16,11 +16,13 @@ public partial class AlarmsView : UserControl
     private static readonly IBrush HighBrush = new SolidColorBrush(Color.Parse("#FEE2E2"));         // light red (666-899)
     private static readonly IBrush CriticalBrush = new SolidColorBrush(Color.Parse("#FECACA"));     // red (900-1000)
 
+    /// <summary>Initializes a new instance of the <see cref="AlarmsView"/> class.</summary>
     public AlarmsView()
     {
         InitializeComponent();
     }
 
+    /// <inheritdoc />
     protected override void OnLoaded(RoutedEventArgs e)
     {
         base.OnLoaded(e);

src/Client/ZB.MOM.WW.OtOpcUa.Client.UI/Views/BrowseTreeView.axaml.cs

@@ -4,6 +4,7 @@ namespace ZB.MOM.WW.OtOpcUa.Client.UI.Views;
 
 public partial class BrowseTreeView : UserControl
 {
+    /// <summary>Initializes a new instance of the BrowseTreeView.</summary>
     public BrowseTreeView()
     {
         InitializeComponent();

src/Client/ZB.MOM.WW.OtOpcUa.Client.UI/Views/HistoryView.axaml.cs

@@ -4,6 +4,7 @@ namespace ZB.MOM.WW.OtOpcUa.Client.UI.Views;
 
 public partial class HistoryView : UserControl
 {
+    /// <summary>Initializes a new instance of the HistoryView control.</summary>
     public HistoryView()
     {
         InitializeComponent();

src/Client/ZB.MOM.WW.OtOpcUa.Client.UI/Views/MainWindow.axaml.cs

@@ -11,6 +11,7 @@ namespace ZB.MOM.WW.OtOpcUa.Client.UI.Views;
 
 public partial class MainWindow : Window
 {
+    /// <summary>Initializes a new instance of the MainWindow, loading the application icon.</summary>
     public MainWindow()
     {
         InitializeComponent();
@@ -51,6 +52,7 @@ public partial class MainWindow : Window
         }
     }
 
+    /// <inheritdoc />
     protected override void OnLoaded(RoutedEventArgs e)
     {
         base.OnLoaded(e);
@@ -157,6 +159,7 @@ public partial class MainWindow : Window
             vm.CertificateStorePath = picked;
     }
 
+    /// <inheritdoc />
     protected override void OnClosing(WindowClosingEventArgs e)
     {
         if (DataContext is MainWindowViewModel vm)

src/Client/ZB.MOM.WW.OtOpcUa.Client.UI/Views/ReadWriteView.axaml.cs

@@ -4,6 +4,7 @@ namespace ZB.MOM.WW.OtOpcUa.Client.UI.Views;
 
 public partial class ReadWriteView : UserControl
 {
+    /// <summary>Initializes a new instance of the ReadWriteView class.</summary>
     public ReadWriteView()
     {
         InitializeComponent();

src/Client/ZB.MOM.WW.OtOpcUa.Client.UI/Views/SubscriptionsView.axaml.cs

@@ -8,11 +8,13 @@ namespace ZB.MOM.WW.OtOpcUa.Client.UI.Views;
 
 public partial class SubscriptionsView : UserControl
 {
+    /// <summary>Initializes a new instance of the <see cref="SubscriptionsView"/> class.</summary>
     public SubscriptionsView()
     {
         InitializeComponent();
     }
 
+    /// <inheritdoc />
     protected override void OnLoaded(RoutedEventArgs e)
     {
         base.OnLoaded(e);

src/Client/ZB.MOM.WW.OtOpcUa.Client.UI/Views/WriteValueWindow.axaml.cs

@@ -10,6 +10,7 @@ public partial class WriteValueWindow : Window
     private readonly SubscriptionsViewModel _subscriptionsVm;
     private readonly string _nodeId;
 
+    /// <summary>Initializes a default instance of the WriteValueWindow for XAML designer support.</summary>
     public WriteValueWindow()
     {
         InitializeComponent();
@@ -17,6 +18,10 @@ public partial class WriteValueWindow : Window
         _nodeId = string.Empty;
     }
 
+    /// <summary>Initializes a WriteValueWindow with the node to write and its current value.</summary>
+    /// <param name="subscriptionsVm">The subscriptions view model for write operations.</param>
+    /// <param name="nodeId">The OPC UA node ID to write to.</param>
+    /// <param name="currentValue">The current value of the node, or null if unknown.</param>
     public WriteValueWindow(SubscriptionsViewModel subscriptionsVm, string nodeId, string? currentValue)
     {
         InitializeComponent();

src/Core/ZB.MOM.WW.OtOpcUa.Cluster/AkkaClusterOptions.cs

@@ -4,8 +4,13 @@ public sealed class AkkaClusterOptions
 {
     public const string SectionName = "Cluster";
 
+    /// <summary>Gets or sets the Akka system name.</summary>
     public string SystemName { get; set; } = "otopcua";
+
+    /// <summary>Gets or sets the hostname to bind to (default 0.0.0.0).</summary>
     public string Hostname { get; set; } = "0.0.0.0";
+
+    /// <summary>Gets or sets the port to listen on (default 4053).</summary>
     public int Port { get; set; } = 4053;
 
     /// <summary>
@@ -15,6 +20,7 @@ public sealed class AkkaClusterOptions
     /// </summary>
     public string PublicHostname { get; set; } = "127.0.0.1";
 
+    /// <summary>Gets or sets the seed nodes for cluster bootstrapping.</summary>
     public string[] SeedNodes { get; set; } = Array.Empty<string>();
 
     /// <summary>

src/Core/ZB.MOM.WW.OtOpcUa.Cluster/ClusterRoleInfo.cs

@@ -25,6 +25,10 @@ public sealed class ClusterRoleInfo : IClusterRoleInfo, IDisposable
     private readonly Dictionary<string, HashSet<Member>> _membersByRole = new(StringComparer.Ordinal);
     private IActorRef? _subscriber;
 
+    /// <summary>Initializes a new instance of the ClusterRoleInfo class.</summary>
+    /// <param name="system">The Akka actor system.</param>
+    /// <param name="options">The cluster configuration options.</param>
+    /// <param name="logger">The logger instance.</param>
     public ClusterRoleInfo(ActorSystem system, IOptions<AkkaClusterOptions> options, ILogger<ClusterRoleInfo> logger)
     {
         _cluster = Akka.Cluster.Cluster.Get(system);
@@ -39,12 +43,20 @@ public sealed class ClusterRoleInfo : IClusterRoleInfo, IDisposable
         _subscriber = system.ActorOf(Props.Create(() => new SubscriberActor(this)), "clusterroleinfo-subscriber");
     }
 
+    /// <summary>Gets the local cluster node identifier.</summary>
     public CommonsNodeId LocalNode => _localNode;
 
+    /// <summary>Gets the set of roles assigned to the local node.</summary>
     public IReadOnlySet<string> LocalRoles => _localRoles;
 
+    /// <summary>Checks if the local node has a specific role.</summary>
+    /// <param name="role">The role name to check.</param>
+    /// <returns>True if the local node has the specified role; otherwise false.</returns>
     public bool HasRole(string role) => _localRoles.Contains(role);
 
+    /// <summary>Gets all cluster members that have a specific role.</summary>
+    /// <param name="role">The role name.</param>
+    /// <returns>A read-only list of node IDs with the specified role.</returns>
     public IReadOnlyList<CommonsNodeId> MembersWithRole(string role)
     {
         lock (_lock)
@@ -56,6 +68,9 @@ public sealed class ClusterRoleInfo : IClusterRoleInfo, IDisposable
         }
     }
 
+    /// <summary>Gets the current leader node for a specific role.</summary>
+    /// <param name="role">The role name.</param>
+    /// <returns>The node ID of the current role leader, or null if no leader is elected.</returns>
     public CommonsNodeId? RoleLeader(string role)
     {
         lock (_lock)
@@ -66,6 +81,7 @@ public sealed class ClusterRoleInfo : IClusterRoleInfo, IDisposable
         }
     }
 
+    /// <summary>Occurs when the leader for a role changes.</summary>
     public event EventHandler<RoleLeaderChangedEventArgs>? RoleLeaderChanged;
 
     private void SeedFromCurrentState()
@@ -91,6 +107,8 @@ public sealed class ClusterRoleInfo : IClusterRoleInfo, IDisposable
         }
     }
 
+    /// <summary>Handles a cluster member event (member up/removed).</summary>
+    /// <param name="evt">The member event from the cluster.</param>
     internal void HandleMemberEvent(ClusterEvent.IMemberEvent evt)
     {
         lock (_lock)
@@ -114,6 +132,8 @@ public sealed class ClusterRoleInfo : IClusterRoleInfo, IDisposable
         }
     }
 
+    /// <summary>Handles a role leader change event.</summary>
+    /// <param name="evt">The role leader changed event from the cluster.</param>
     internal void HandleRoleLeaderChanged(ClusterEvent.RoleLeaderChanged evt)
     {
         CommonsNodeId? previous = null;
@@ -156,6 +176,7 @@ public sealed class ClusterRoleInfo : IClusterRoleInfo, IDisposable
     private static CommonsNodeId ToNodeId(Akka.Actor.Address address) =>
         CommonsNodeId.Parse($"{address.Host ?? string.Empty}:{address.Port ?? 0}");
 
+    /// <summary>Disposes the ClusterRoleInfo and stops the subscriber actor.</summary>
     public void Dispose()
     {
         _subscriber?.Tell(PoisonPill.Instance);
@@ -164,6 +185,8 @@ public sealed class ClusterRoleInfo : IClusterRoleInfo, IDisposable
 
     private sealed class SubscriberActor : ReceiveActor
     {
+        /// <summary>Initializes a new instance of the SubscriberActor class.</summary>
+        /// <param name="owner">The ClusterRoleInfo instance to forward events to.</param>
         public SubscriberActor(ClusterRoleInfo owner)
         {
             Receive<ClusterEvent.IMemberEvent>(e => owner.HandleMemberEvent(e));
@@ -172,6 +195,7 @@ public sealed class ClusterRoleInfo : IClusterRoleInfo, IDisposable
             Receive<ClusterEvent.CurrentClusterState>(_ => { /* seeded from initial snapshot */ });
         }
 
+        /// <inheritdoc />
         protected override void PreStart()
         {
             Akka.Cluster.Cluster.Get(Context.System).Subscribe(
@@ -182,6 +206,7 @@ public sealed class ClusterRoleInfo : IClusterRoleInfo, IDisposable
                 typeof(ClusterEvent.RoleLeaderChanged));
         }
 
+        /// <inheritdoc />
         protected override void PostStop() =>
             Akka.Cluster.Cluster.Get(Context.System).Unsubscribe(Self);
     }

src/Core/ZB.MOM.WW.OtOpcUa.Cluster/HoconLoader.cs

@@ -1,9 +1,12 @@
 namespace ZB.MOM.WW.OtOpcUa.Cluster;
 
+/// <summary>Loads embedded HOCON configuration resources.</summary>
 public static class HoconLoader
 {
     private const string ResourceName = "ZB.MOM.WW.OtOpcUa.Cluster.Resources.akka.conf";
 
+    /// <summary>Loads the base Akka configuration from embedded resources.</summary>
+    /// <returns>The loaded HOCON configuration as a string.</returns>
     public static string LoadBaseConfig()
     {
         using var stream = typeof(HoconLoader).Assembly.GetManifestResourceStream(ResourceName)

src/Core/ZB.MOM.WW.OtOpcUa.Cluster/RoleParser.cs

@@ -7,6 +7,8 @@ public static class RoleParser
         "admin", "driver", "dev",
     };
 
+    /// <summary>Parses a comma-separated string of role names into a validated array.</summary>
+    /// <param name="raw">The raw role string to parse.</param>
     public static string[] Parse(string? raw)
     {
         if (string.IsNullOrWhiteSpace(raw)) return Array.Empty<string>();

src/Core/ZB.MOM.WW.OtOpcUa.Cluster/ServiceCollectionExtensions.cs

@@ -16,6 +16,8 @@ public static class ServiceCollectionExtensions
     /// configurator via <see cref="WithOtOpcUaClusterBootstrap"/> — keeping the entire Akka graph
     /// under Akka.Hosting's management so cluster singletons land on the same ActorSystem.
     /// </summary>
+    /// <param name="services">The service collection to configure.</param>
+    /// <param name="configuration">The application configuration containing cluster options.</param>
     public static IServiceCollection AddOtOpcUaCluster(this IServiceCollection services, IConfiguration configuration)
     {
         services.AddOptions<AkkaClusterOptions>()
@@ -41,6 +43,8 @@ public static class ServiceCollectionExtensions
     /// });
     /// </code>
     /// </summary>
+    /// <param name="builder">The Akka configuration builder to configure.</param>
+    /// <param name="serviceProvider">The service provider for resolving cluster options.</param>
     public static AkkaConfigurationBuilder WithOtOpcUaClusterBootstrap(
         this AkkaConfigurationBuilder builder,
         IServiceProvider serviceProvider)

src/Core/ZB.MOM.WW.OtOpcUa.Commons/Engines/IAlarmActorStateStore.cs

@@ -10,7 +10,14 @@ namespace ZB.MOM.WW.OtOpcUa.Commons.Engines;
 /// </summary>
 public interface IAlarmActorStateStore
 {
+    /// <summary>Loads the persisted state snapshot for an alarm actor.</summary>
+    /// <param name="alarmId">The alarm identifier.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>The alarm state snapshot if found; null if the alarm has no persisted state.</returns>
     Task<AlarmActorStateSnapshot?> LoadAsync(string alarmId, CancellationToken ct);
+    /// <summary>Saves the alarm actor state snapshot.</summary>
+    /// <param name="snapshot">The state snapshot to persist.</param>
+    /// <param name="ct">Cancellation token.</param>
     Task SaveAsync(AlarmActorStateSnapshot snapshot, CancellationToken ct);
 }
 
@@ -34,8 +41,14 @@ public sealed class NullAlarmActorStateStore : IAlarmActorStateStore
 {
     public static readonly NullAlarmActorStateStore Instance = new();
     private NullAlarmActorStateStore() { }
+    /// <summary>Always returns null, indicating no persisted state.</summary>
+    /// <param name="alarmId">The alarm identifier (unused).</param>
+    /// <param name="ct">Cancellation token (unused).</param>
     public Task<AlarmActorStateSnapshot?> LoadAsync(string alarmId, CancellationToken ct) =>
         Task.FromResult<AlarmActorStateSnapshot?>(null);
+    /// <summary>Completes immediately without persisting anything.</summary>
+    /// <param name="snapshot">The state snapshot (ignored).</param>
+    /// <param name="ct">Cancellation token (unused).</param>
     public Task SaveAsync(AlarmActorStateSnapshot snapshot, CancellationToken ct) =>
         Task.CompletedTask;
 }

src/Core/ZB.MOM.WW.OtOpcUa.Commons/Engines/IScriptedAlarmEvaluator.cs

@@ -8,6 +8,11 @@ namespace ZB.MOM.WW.OtOpcUa.Commons.Engines;
 /// </summary>
 public interface IScriptedAlarmEvaluator
 {
+    /// <summary>Evaluates an alarm predicate against the provided dependencies.</summary>
+    /// <param name="alarmId">The unique identifier of the alarm being evaluated.</param>
+    /// <param name="predicate">The predicate expression to evaluate.</param>
+    /// <param name="dependencies">Read-only dictionary of variable names to values for predicate evaluation.</param>
+    /// <returns>Result containing success flag, alarm active state, and optional failure reason.</returns>
     ScriptedAlarmEvalResult Evaluate(string alarmId, string predicate, IReadOnlyDictionary<string, object?> dependencies);
 }
 
@@ -15,7 +20,14 @@ public interface IScriptedAlarmEvaluator
 /// <c>Success</c> is true; on failure the caller should keep the prior state and log Reason.</summary>
 public sealed record ScriptedAlarmEvalResult(bool Success, bool Active, string? Reason)
 {
+    /// <summary>Creates a successful alarm evaluation result with the given active state.</summary>
+    /// <param name="active">Whether the alarm condition is active.</param>
+    /// <returns>A successful evaluation result.</returns>
     public static ScriptedAlarmEvalResult Ok(bool active) => new(true, active, null);
+
+    /// <summary>Creates a failed alarm evaluation result with the given reason.</summary>
+    /// <param name="reason">Description of the evaluation failure cause.</param>
+    /// <returns>A failed evaluation result.</returns>
     public static ScriptedAlarmEvalResult Failure(string reason) => new(false, false, reason);
 }
 
@@ -25,6 +37,11 @@ public sealed class NullScriptedAlarmEvaluator : IScriptedAlarmEvaluator
 {
     public static readonly NullScriptedAlarmEvaluator Instance = new();
     private NullScriptedAlarmEvaluator() { }
+    /// <summary>Returns an inactive alarm result for every evaluation (safe no-op behavior).</summary>
+    /// <param name="alarmId">The alarm identifier (ignored).</param>
+    /// <param name="predicate">The predicate expression (ignored).</param>
+    /// <param name="dependencies">The variable dependencies (ignored).</param>
+    /// <returns>Always returns an inactive alarm result.</returns>
     public ScriptedAlarmEvalResult Evaluate(string alarmId, string predicate, IReadOnlyDictionary<string, object?> dependencies)
         => ScriptedAlarmEvalResult.Ok(active: false);
 }

src/Core/ZB.MOM.WW.OtOpcUa.Commons/Engines/IVirtualTagEvaluator.cs

@@ -13,6 +13,10 @@ public interface IVirtualTagEvaluator
     ///     <paramref name="dependencies"/>. Implementations must not throw — script failures
     ///     are reported via <see cref="VirtualTagEvalResult.Failure"/>.
     /// </summary>
+    /// <param name="virtualTagId">The unique identifier of the virtual tag being evaluated.</param>
+    /// <param name="expression">The expression string to evaluate.</param>
+    /// <param name="dependencies">Read-only dictionary of variable names to values for expression evaluation.</param>
+    /// <returns>Result containing success flag, evaluated value, and optional failure reason.</returns>
     VirtualTagEvalResult Evaluate(string virtualTagId, string expression, IReadOnlyDictionary<string, object?> dependencies);
 }
 
@@ -21,7 +25,15 @@ public interface IVirtualTagEvaluator
 public sealed record VirtualTagEvalResult(bool Success, object? Value, string? Reason)
 {
     public static readonly VirtualTagEvalResult NoChange = new(true, null, "no-change");
+
+    /// <summary>Creates a successful evaluation result with the given value.</summary>
+    /// <param name="value">The evaluated value.</param>
+    /// <returns>A successful evaluation result.</returns>
     public static VirtualTagEvalResult Ok(object? value) => new(true, value, null);
+
+    /// <summary>Creates a failed evaluation result with the given reason.</summary>
+    /// <param name="reason">Description of the failure cause.</param>
+    /// <returns>A failed evaluation result.</returns>
     public static VirtualTagEvalResult Failure(string reason) => new(false, null, reason);
 }
 
@@ -31,6 +43,11 @@ public sealed class NullVirtualTagEvaluator : IVirtualTagEvaluator
 {
     public static readonly NullVirtualTagEvaluator Instance = new();
     private NullVirtualTagEvaluator() { }
+    /// <summary>Returns <see cref="VirtualTagEvalResult.NoChange"/> for every evaluation.</summary>
+    /// <param name="virtualTagId">The virtual tag identifier (ignored).</param>
+    /// <param name="expression">The expression string (ignored).</param>
+    /// <param name="dependencies">The variable dependencies (ignored).</param>
+    /// <returns>Always returns <see cref="VirtualTagEvalResult.NoChange"/>.</returns>
     public VirtualTagEvalResult Evaluate(string virtualTagId, string expression, IReadOnlyDictionary<string, object?> dependencies)
         => VirtualTagEvalResult.NoChange;
 }

src/Core/ZB.MOM.WW.OtOpcUa.Commons/Interfaces/IAdminOperationsClient.cs

@@ -9,5 +9,9 @@ namespace ZB.MOM.WW.OtOpcUa.Commons.Interfaces;
 /// </summary>
 public interface IAdminOperationsClient
 {
+    /// <summary>Starts a new deployment on the cluster-singleton admin operations actor.</summary>
+    /// <param name="createdBy">The user or system identifier triggering the deployment.</param>
+    /// <param name="ct">The cancellation token.</param>
+    /// <returns>A task representing the asynchronous operation containing the deployment start result.</returns>
     Task<StartDeploymentResult> StartDeploymentAsync(string createdBy, CancellationToken ct);
 }

src/Core/ZB.MOM.WW.OtOpcUa.Commons/Interfaces/IClusterRoleInfo.cs

@@ -10,11 +10,23 @@ namespace ZB.MOM.WW.OtOpcUa.Commons.Interfaces;
 /// </summary>
 public interface IClusterRoleInfo
 {
+    /// <summary>Gets the local cluster node identifier.</summary>
     NodeId LocalNode { get; }
+    /// <summary>Gets the set of roles assigned to the local node.</summary>
     IReadOnlySet<string> LocalRoles { get; }
+    /// <summary>Checks if the local node has the specified role.</summary>
+    /// <param name="role">Role name to check.</param>
+    /// <returns>True if the local node has the role; otherwise, false.</returns>
     bool HasRole(string role);
+    /// <summary>Gets all nodes assigned to the specified role.</summary>
+    /// <param name="role">Role name to query.</param>
+    /// <returns>List of node identifiers with the role.</returns>
     IReadOnlyList<NodeId> MembersWithRole(string role);
+    /// <summary>Gets the leader node for the specified role, or null if no leader is elected.</summary>
+    /// <param name="role">Role name to query.</param>
+    /// <returns>The leader node identifier, or null if no leader exists.</returns>
     NodeId? RoleLeader(string role);
 
+    /// <summary>Occurs when the leader of a role changes.</summary>
     event EventHandler<RoleLeaderChangedEventArgs>? RoleLeaderChanged;
 }

src/Core/ZB.MOM.WW.OtOpcUa.Commons/Interfaces/IFleetDiagnosticsClient.cs

@@ -8,5 +8,8 @@ namespace ZB.MOM.WW.OtOpcUa.Commons.Interfaces;
 /// </summary>
 public interface IFleetDiagnosticsClient
 {
+    /// <summary>Gets diagnostics for the specified node.</summary>
+    /// <param name="nodeId">The node ID to retrieve diagnostics for.</param>
+    /// <param name="ct">The cancellation token.</param>
     Task<NodeDiagnosticsSnapshot> GetDiagnosticsAsync(NodeId nodeId, CancellationToken ct);
 }

src/Core/ZB.MOM.WW.OtOpcUa.Commons/Interfaces/RoleLeaderChangedEventArgs.cs

@@ -2,9 +2,15 @@ using ZB.MOM.WW.OtOpcUa.Commons.Types;
 
 namespace ZB.MOM.WW.OtOpcUa.Commons.Interfaces;
 
+/// <summary>Event arguments for role leader change notifications.</summary>
 public sealed class RoleLeaderChangedEventArgs : EventArgs
 {
+    /// <summary>Gets the role name that changed leadership.</summary>
     public required string Role { get; init; }
+
+    /// <summary>Gets the previous leader node ID, or null if there was no previous leader.</summary>
     public required NodeId? PreviousLeader { get; init; }
+
+    /// <summary>Gets the new leader node ID, or null if the role is now leaderless.</summary>
     public required NodeId? NewLeader { get; init; }
 }

src/Core/ZB.MOM.WW.OtOpcUa.Commons/Observability/OtOpcUaTelemetry.cs

@@ -68,6 +68,7 @@ public static class OtOpcUaTelemetry
     /// Starts a deploy span tagged with the deployment id. Caller disposes to close. Returns
     /// null when no listener is attached so the call site stays cheap on undecorated builds.
     /// </summary>
+    /// <param name="deploymentId">The deployment identifier to tag the span with.</param>
     public static Activity? StartDeployApplySpan(string deploymentId)
     {
         var activity = ActivitySource.StartActivity("otopcua.deploy.apply", ActivityKind.Internal);

src/Core/ZB.MOM.WW.OtOpcUa.Commons/OpcUa/DeferredAddressSpaceSink.cs

@@ -18,17 +18,41 @@ public sealed class DeferredAddressSpaceSink : IOpcUaAddressSpaceSink
 
     /// <summary>Swap in the production sink. Pass <c>null</c> to revert to the null sink
     /// (used during graceful shutdown so post-stop writes don't hit a half-disposed manager).</summary>
+    /// <param name="sink">The sink implementation to use, or null to use the null sink.</param>
     public void SetSink(IOpcUaAddressSpaceSink? sink) =>
         _inner = sink ?? NullOpcUaAddressSpaceSink.Instance;
 
+    /// <summary>Writes a value to the OPC UA address space through the inner sink.</summary>
+    /// <param name="nodeId">The node ID of the variable.</param>
+    /// <param name="value">The value to write.</param>
+    /// <param name="quality">The OPC UA quality value.</param>
+    /// <param name="sourceTimestampUtc">The source timestamp in UTC.</param>
     public void WriteValue(string nodeId, object? value, OpcUaQuality quality, DateTime sourceTimestampUtc)
         => _inner.WriteValue(nodeId, value, quality, sourceTimestampUtc);
 
+    /// <summary>Writes an alarm state through the inner sink.</summary>
+    /// <param name="alarmNodeId">The node ID of the alarm condition.</param>
+    /// <param name="active">Whether the alarm is active.</param>
+    /// <param name="acknowledged">Whether the alarm has been acknowledged.</param>
+    /// <param name="sourceTimestampUtc">The source timestamp in UTC.</param>
     public void WriteAlarmState(string alarmNodeId, bool active, bool acknowledged, DateTime sourceTimestampUtc)
         => _inner.WriteAlarmState(alarmNodeId, active, acknowledged, sourceTimestampUtc);
 
+    /// <summary>Ensures a folder exists in the address space through the inner sink.</summary>
+    /// <param name="folderNodeId">The node ID of the folder.</param>
+    /// <param name="parentNodeId">The node ID of the parent folder, or null for root.</param>
+    /// <param name="displayName">The display name of the folder.</param>
     public void EnsureFolder(string folderNodeId, string? parentNodeId, string displayName)
         => _inner.EnsureFolder(folderNodeId, parentNodeId, displayName);
 
+    /// <summary>Ensures a variable exists in the address space through the inner sink.</summary>
+    /// <param name="variableNodeId">The node ID of the variable.</param>
+    /// <param name="parentFolderNodeId">The node ID of the parent folder, or null for root.</param>
+    /// <param name="displayName">The display name of the variable.</param>
+    /// <param name="dataType">The OPC UA data type of the variable.</param>
+    public void EnsureVariable(string variableNodeId, string? parentFolderNodeId, string displayName, string dataType)
+        => _inner.EnsureVariable(variableNodeId, parentFolderNodeId, displayName, dataType);
+
+    /// <summary>Rebuilds the address space through the inner sink.</summary>
     public void RebuildAddressSpace() => _inner.RebuildAddressSpace();
 }

src/Core/ZB.MOM.WW.OtOpcUa.Commons/OpcUa/DeferredServiceLevelPublisher.cs

@@ -12,8 +12,11 @@ public sealed class DeferredServiceLevelPublisher : IServiceLevelPublisher
     private volatile IServiceLevelPublisher _inner = NullServiceLevelPublisher.Instance;
 
     /// <summary>Swap the underlying publisher. Pass null to revert to the Null no-op.</summary>
+    /// <param name="inner">The publisher implementation to use, or null to use the null publisher.</param>
     public void SetInner(IServiceLevelPublisher? inner) =>
         _inner = inner ?? NullServiceLevelPublisher.Instance;
 
+    /// <summary>Publishes a service level value to the inner publisher.</summary>
+    /// <param name="serviceLevel">The service level to publish.</param>
     public void Publish(byte serviceLevel) => _inner.Publish(serviceLevel);
 }

src/Core/ZB.MOM.WW.OtOpcUa.Commons/OpcUa/IOpcUaAddressSpaceSink.cs

@@ -9,9 +9,17 @@ namespace ZB.MOM.WW.OtOpcUa.Commons.OpcUa;
 public interface IOpcUaAddressSpaceSink
 {
     /// <summary>Write a Variable node's current value + quality + source timestamp.</summary>
+    /// <param name="nodeId">The OPC UA node ID of the variable.</param>
+    /// <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);
 
     /// <summary>Write an alarm-condition Variable's active/acknowledged state.</summary>
+    /// <param name="alarmNodeId">The OPC UA node ID of the alarm.</param>
+    /// <param name="active">Whether the alarm is active.</param>
+    /// <param name="acknowledged">Whether the alarm has been acknowledged.</param>
+    /// <param name="sourceTimestampUtc">The source timestamp in UTC.</param>
     void WriteAlarmState(string alarmNodeId, bool active, bool acknowledged, DateTime sourceTimestampUtc);
 
     /// <summary>
@@ -20,8 +28,24 @@ public interface IOpcUaAddressSpaceSink
     ///     <paramref name="parentNodeId"/> is null the folder is parented under the namespace
     ///     root. Idempotent: calling twice with the same id is safe.
     /// </summary>
+    /// <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);
 
+    /// <summary>
+    ///     Ensure a Variable node exists at <paramref name="variableNodeId"/>, parented under
+    ///     <paramref name="parentFolderNodeId"/> (or the namespace root when null). Created with
+    ///     Bad quality + null value; subsequent <see cref="WriteValue"/> calls update both.
+    ///     Used by <c>Phase7Applier</c> to materialise Galaxy / SystemPlatform tags ahead of any
+    ///     driver-side subscribe so OPC UA clients can browse them. Idempotent.
+    /// </summary>
+    /// <param name="variableNodeId">The OPC UA node ID for the variable.</param>
+    /// <param name="parentFolderNodeId">The parent folder node ID, or null for namespace root.</param>
+    /// <param name="displayName">The display name for the variable.</param>
+    /// <param name="dataType">OPC UA built-in type name ("Boolean" / "Int32" / "Float" / etc.).</param>
+    void EnsureVariable(string variableNodeId, string? parentFolderNodeId, string displayName, string dataType);
+
     /// <summary>
     ///     Tear down + repopulate the address space. Called by <c>OpcUaPublishActor</c> after a
     ///     successful deployment apply so the node manager reflects the new config. Idempotent.
@@ -39,8 +63,19 @@ public sealed class NullOpcUaAddressSpaceSink : IOpcUaAddressSpaceSink
 {
     public static readonly NullOpcUaAddressSpaceSink Instance = new();
     private NullOpcUaAddressSpaceSink() { }
+
+    /// <inheritdoc />
     public void WriteValue(string nodeId, object? value, OpcUaQuality quality, DateTime sourceTimestampUtc) { }
+
+    /// <inheritdoc />
     public void WriteAlarmState(string alarmNodeId, bool active, bool acknowledged, DateTime sourceTimestampUtc) { }
+
+    /// <inheritdoc />
     public void EnsureFolder(string folderNodeId, string? parentNodeId, string displayName) { }
+
+    /// <inheritdoc />
+    public void EnsureVariable(string variableNodeId, string? parentFolderNodeId, string displayName, string dataType) { }
+
+    /// <inheritdoc />
     public void RebuildAddressSpace() { }
 }

src/Core/ZB.MOM.WW.OtOpcUa.Commons/OpcUa/IServiceLevelPublisher.cs

@@ -8,6 +8,8 @@ namespace ZB.MOM.WW.OtOpcUa.Commons.OpcUa;
 /// </summary>
 public interface IServiceLevelPublisher
 {
+    /// <summary>Publishes the service level value to the OPC UA Server object.</summary>
+    /// <param name="serviceLevel">The service level value (0-255).</param>
     void Publish(byte serviceLevel);
 }
 
@@ -17,6 +19,11 @@ public sealed class NullServiceLevelPublisher : IServiceLevelPublisher
 {
     public static readonly NullServiceLevelPublisher Instance = new();
     private NullServiceLevelPublisher() { }
+
+    /// <summary>Gets the last published service level value.</summary>
     public byte LastPublished { get; private set; }
+
+    /// <summary>Records the service level value without publishing.</summary>
+    /// <param name="serviceLevel">The service level value (0-255).</param>
     public void Publish(byte serviceLevel) => LastPublished = serviceLevel;
 }

src/Core/ZB.MOM.WW.OtOpcUa.Commons/Types/CorrelationId.cs

@@ -2,9 +2,16 @@ namespace ZB.MOM.WW.OtOpcUa.Commons.Types;
 
 public readonly record struct CorrelationId(Guid Value)
 {
+    /// <summary>Creates a new CorrelationId with a randomly generated GUID.</summary>
     public static CorrelationId NewId() => new(Guid.NewGuid());
+    /// <inheritdoc />
     public override string ToString() => Value.ToString("N");
+    /// <summary>Parses a lowercase hex string without hyphens into a CorrelationId.</summary>
+    /// <param name="s">The string to parse.</param>
     public static CorrelationId Parse(string s) => new(Guid.ParseExact(s, "N"));
+    /// <summary>Attempts to parse a lowercase hex string without hyphens into a CorrelationId.</summary>
+    /// <param name="s">The string to parse, or null.</param>
+    /// <param name="id">The resulting CorrelationId if parsing succeeds.</param>
     public static bool TryParse(string? s, out CorrelationId id)
     {
         if (Guid.TryParseExact(s, "N", out var g)) { id = new CorrelationId(g); return true; }

src/Core/ZB.MOM.WW.OtOpcUa.Commons/Types/DeploymentId.cs

@@ -2,9 +2,22 @@ namespace ZB.MOM.WW.OtOpcUa.Commons.Types;
 
 public readonly record struct DeploymentId(Guid Value)
 {
+    /// <summary>Creates a new deployment ID with a random GUID.</summary>
+    /// <returns>A new DeploymentId.</returns>
     public static DeploymentId NewId() => new(Guid.NewGuid());
+
+    /// <inheritdoc />
     public override string ToString() => Value.ToString("N");
+
+    /// <summary>Parses a deployment ID from a hex string without hyphens.</summary>
+    /// <param name="s">The hex string to parse.</param>
+    /// <returns>The parsed DeploymentId.</returns>
     public static DeploymentId Parse(string s) => new(Guid.ParseExact(s, "N"));
+
+    /// <summary>Attempts to parse a deployment ID from a hex string without hyphens.</summary>
+    /// <param name="s">The hex string to parse, or null.</param>
+    /// <param name="id">The parsed DeploymentId if successful, or default.</param>
+    /// <returns>True if parsing succeeded; false otherwise.</returns>
     public static bool TryParse(string? s, out DeploymentId id)
     {
         if (Guid.TryParseExact(s, "N", out var g)) { id = new DeploymentId(g); return true; }

src/Core/ZB.MOM.WW.OtOpcUa.Commons/Types/ExecutionId.cs

@@ -2,9 +2,22 @@ namespace ZB.MOM.WW.OtOpcUa.Commons.Types;
 
 public readonly record struct ExecutionId(Guid Value)
 {
+    /// <summary>Creates a new execution ID with a randomly generated GUID.</summary>
+    /// <returns>A new ExecutionId instance.</returns>
     public static ExecutionId NewId() => new(Guid.NewGuid());
+
+    /// <inheritdoc />
     public override string ToString() => Value.ToString("N");
+
+    /// <summary>Parses the specified string into an ExecutionId in format N.</summary>
+    /// <param name="s">The string to parse.</param>
+    /// <returns>The parsed ExecutionId.</returns>
     public static ExecutionId Parse(string s) => new(Guid.ParseExact(s, "N"));
+
+    /// <summary>Tries to parse the specified string into an ExecutionId in format N.</summary>
+    /// <param name="s">The string to parse, or null.</param>
+    /// <param name="id">The parsed ExecutionId, or default if parsing fails.</param>
+    /// <returns>true if parsing succeeded; otherwise, false.</returns>
     public static bool TryParse(string? s, out ExecutionId id)
     {
         if (Guid.TryParseExact(s, "N", out var g)) { id = new ExecutionId(g); return true; }

src/Core/ZB.MOM.WW.OtOpcUa.Commons/Types/NodeId.cs

@@ -7,11 +7,22 @@ namespace ZB.MOM.WW.OtOpcUa.Commons.Types;
 /// </summary>
 public readonly record struct NodeId(string Value)
 {
+    /// <inheritdoc />
     public override string ToString() => Value;
+
+    /// <summary>Parses a string into a NodeId.</summary>
+    /// <param name="s">The string to parse.</param>
+    /// <returns>A new NodeId instance.</returns>
+    /// <exception cref="ArgumentException">Thrown when the string is null, empty, or whitespace.</exception>
     public static NodeId Parse(string s) =>
         string.IsNullOrWhiteSpace(s)
             ? throw new ArgumentException("NodeId value cannot be empty.", nameof(s))
             : new NodeId(s);
+
+    /// <summary>Attempts to parse a string into a NodeId.</summary>
+    /// <param name="s">The string to parse.</param>
+    /// <param name="id">The parsed NodeId if successful.</param>
+    /// <returns>True if the parse succeeded; otherwise false.</returns>
     public static bool TryParse(string? s, out NodeId id)
     {
         if (!string.IsNullOrWhiteSpace(s)) { id = new NodeId(s); return true; }

src/Core/ZB.MOM.WW.OtOpcUa.Commons/Types/RevisionHash.cs

@@ -6,11 +6,24 @@ namespace ZB.MOM.WW.OtOpcUa.Commons.Types;
 /// </summary>
 public readonly record struct RevisionHash(string Value)
 {
+    /// <inheritdoc />
     public override string ToString() => Value;
+    /// <summary>
+    /// Parses a string into a <see cref="RevisionHash"/>.
+    /// </summary>
+    /// <param name="s">The string to parse.</param>
+    /// <returns>A <see cref="RevisionHash"/> instance.</returns>
+    /// <exception cref="ArgumentException">Thrown if the input is null, empty, or whitespace.</exception>
     public static RevisionHash Parse(string s) =>
         string.IsNullOrWhiteSpace(s)
             ? throw new ArgumentException("RevisionHash value cannot be empty.", nameof(s))
             : new RevisionHash(s);
+    /// <summary>
+    /// Attempts to parse a string into a <see cref="RevisionHash"/>.
+    /// </summary>
+    /// <param name="s">The string to parse.</param>
+    /// <param name="hash">The parsed hash, or default if parsing fails.</param>
+    /// <returns>True if parsing succeeded; otherwise false.</returns>
     public static bool TryParse(string? s, out RevisionHash hash)
     {
         if (!string.IsNullOrWhiteSpace(s)) { hash = new RevisionHash(s); return true; }

src/Core/ZB.MOM.WW.OtOpcUa.Configuration/DesignTimeDbContextFactory.cs

@@ -17,6 +17,9 @@ namespace ZB.MOM.WW.OtOpcUa.Configuration;
 /// </remarks>
 public sealed class DesignTimeDbContextFactory : IDesignTimeDbContextFactory<OtOpcUaConfigDbContext>
 {
+    /// <summary>Creates a new DbContext instance for design-time operations.</summary>
+    /// <param name="args">Command-line arguments (unused).</param>
+    /// <returns>The configured DbContext instance.</returns>
     public OtOpcUaConfigDbContext CreateDbContext(string[] args)
     {
         var connection = Environment.GetEnvironmentVariable("OTOPCUA_CONFIG_CONNECTION");

src/Core/ZB.MOM.WW.OtOpcUa.Configuration/Entities/ClusterNode.cs

@@ -6,13 +6,16 @@ public sealed class ClusterNode
     /// <summary>Stable per-machine logical ID, e.g. "LINE3-OPCUA-A".</summary>
     public required string NodeId { get; set; }
 
+    /// <summary>The unique identifier of the cluster this node belongs to.</summary>
     public required string ClusterId { get; set; }
 
     /// <summary>Machine hostname / IP.</summary>
     public required string Host { get; set; }
 
+    /// <summary>The OPC UA server port (default 4840).</summary>
     public int OpcUaPort { get; set; } = 4840;
 
+    /// <summary>The dashboard HTTP port (default 8081).</summary>
     public int DashboardPort { get; set; } = 8081;
 
     /// <summary>
@@ -32,15 +35,21 @@ public sealed class ClusterNode
     /// </summary>
     public string? DriverConfigOverridesJson { get; set; }
 
+    /// <summary>Gets or sets a value indicating whether this node is enabled.</summary>
     public bool Enabled { get; set; } = true;
 
+    /// <summary>Gets or sets the timestamp when this node was last seen.</summary>
     public DateTime? LastSeenAt { get; set; }
 
+    /// <summary>Gets or sets the timestamp when this node was created.</summary>
     public DateTime CreatedAt { get; set; } = DateTime.UtcNow;
 
+    /// <summary>Gets or sets the username of who created this node.</summary>
     public required string CreatedBy { get; set; }
 
     // Navigation
+    /// <summary>Gets or sets the cluster this node belongs to.</summary>
     public ServerCluster? Cluster { get; set; }
+    /// <summary>Gets or sets the credentials associated with this node.</summary>
     public ICollection<ClusterNodeCredential> Credentials { get; set; } = [];
 }

src/Core/ZB.MOM.WW.OtOpcUa.Configuration/Entities/ClusterNodeCredential.cs

@@ -8,22 +8,30 @@ namespace ZB.MOM.WW.OtOpcUa.Configuration.Entities;
 /// </summary>
 public sealed class ClusterNodeCredential
 {
+    /// <summary>Gets or sets the credential identifier.</summary>
     public Guid CredentialId { get; set; }
 
+    /// <summary>Gets or sets the node identifier this credential binds to.</summary>
     public required string NodeId { get; set; }
 
+    /// <summary>Gets or sets the credential kind (login, certificate, etc.).</summary>
     public required CredentialKind Kind { get; set; }
 
-    /// <summary>Login name / cert thumbprint / SID / gMSA name.</summary>
+    /// <summary>Gets or sets the credential value (login name / cert thumbprint / SID / gMSA name).</summary>
     public required string Value { get; set; }
 
+    /// <summary>Gets or sets a value indicating whether the credential is enabled.</summary>
     public bool Enabled { get; set; } = true;
 
+    /// <summary>Gets or sets the date/time when the credential was last rotated.</summary>
     public DateTime? RotatedAt { get; set; }
 
+    /// <summary>Gets or sets the date/time when the credential was created.</summary>
     public DateTime CreatedAt { get; set; } = DateTime.UtcNow;
 
+    /// <summary>Gets or sets the user who created the credential.</summary>
     public required string CreatedBy { get; set; }
 
+    /// <summary>Gets or sets the related cluster node.</summary>
     public ClusterNode? Node { get; set; }
 }