fix(cluster,acl): OTOPCUA_ROLES fallback + one string-identity rule (#532, #533)

Two independent defects surfaced in review of #520 stage 3.

#532 — Cluster:Roles had no OTOPCUA_ROLES fallback, despite two doc sites
promising one. A node configured only through the env var — which drives ALL of
Program.cs's conditional wiring, so it reads as the authoritative knob — bound an
empty Roles array and joined the cluster carrying no Akka roles at all. It ran,
served, and logged nothing wrong, while central reported "no driver-role nodes
are Up" and every deployment to it timed out. Not hypothetical: the field fix on
wonder-app-vd03 was to hand-add Cluster__Roles__0/1 to a Windows service's
registry environment. Anyone reading the code to diagnose that box would have
concluded from the XML doc that the fallback was already applied.

AddOtOpcUaCluster now post-configures AkkaClusterOptions through the shared
RoleParser.ResolveEffectiveRoles, so BuildClusterOptions (Akka's own member
roles), ClusterRoleInfo, the ControlPlane singleton scope and
ConfigDbApiKeyStore's ClusterId all see one answer. Two sibling validators
(ConfigSource, Telemetry) read Cluster:Roles directly and were exempting the
exact node they exist for — an env-only driver-only node has no ConfigDb and
could sit on ConfigSource:Mode=Direct unchallenged. They resolve the same way now.

Also collapsed the four open-coded `Roles.FirstOrDefault(IsClusterRole)` +
ClusterIdFromRole copies into RoleParser.ClusterIdFromRoles. They had drifted:
three classified the cluster role ordinally, so a verbatim-bound `Cluster-SITE-A`
yielded a null ClusterId — and a null ClusterId applies NO cluster filter, which
made #528's cross-cluster over-grant guard fail OPEN. IsClusterRole is now
case-insensitive; the ClusterId suffix keeps its authored spelling, because
normalizing it would silently rename the Akka role of a running deployment.

#533 — three string-identity rules in one authorization path. AclScopeRef used
default (ordinal) equality while the trie builder filtered ClusterId and hashed
principals OrdinalIgnoreCase; the deploy gate's cross-cluster check was ordinal
too, which was the worse half — it could reject a whole deploy over a ClusterId
case difference the runtime would have accepted. It only worked because resolver
and builder were handed the same NodeAcl instances.

The rule is now stated once, on AclScopeRef, and applied throughout:
identifiers (ScopeId, ClusterId, Principal) compare OrdinalIgnoreCase; path
segments compare Ordinal. AclScopePathResolver re-keys its own maps rather than
documenting a comparer contract for callers, so the two independent producers —
EF at the gate, artifact JSON on the node — cannot diverge from the outside.
PermissionTrieNode.Children stays Ordinal: those are browse names, and Speed /
speed are two nodes that can coexist under one device.

Split PermissionTrieBuildDiagnosticReason.RetiredScopeKind out of
UnresolvedScope. A legacy FolderSegment row and a typo'd id had the same message
and different remedies.

Falsified: five mutations, each reddening only its own guard — remove the
PostConfigure (3 tests), revert IsClusterRole to ordinal (3), revert AclScopeRef
equality (1), revert the resolver's map comparer (6), revert the gate's
comparisons (2), remove the FolderSegment short-circuit (1).

Test isolation: OTOPCUA_ROLES is process-global and xUnit runs classes in
parallel, so the three validator suites that now resolve effective roles share a
non-parallel collection. Without it, cases passing no roles would intermittently
observe another class's env var.

Full solution build clean; full suite green apart from two pre-existing failures
confirmed identical on 3a6b2a1d (PrimaryGateFailoverTests, and
DriverProbeRegistrationTests expecting 10 probe types where 12 now register)
plus the AbLegacy integration suite, which needs a docker fixture.

Claude-Session: https://claude.ai/code/session_015p7wGqy3YpZNCpDzTpGMKo

docs/Configuration.md

@@ -104,7 +104,11 @@ The checked-in `appsettings*.json` files are deliberately thin: they carry only
 | `Port` | int | `4053` | Cluster transport port. **Duplicated as `ClusterNode.AkkaPort` in the Config DB** — see the note below. |
 | `PublicHostname` | string | `127.0.0.1` | Hostname advertised in cluster gossip; must be reachable by peers. **Duplicated as `ClusterNode.Host`** — see the note below. |
 | `SeedNodes` | string[] | `[]` | Seed nodes for bootstrapping. **Ordered:** a node that appears in its own list must be entry 0 (only `seed-nodes[0]` can form a new cluster), or the host refuses to start — see [Redundancy.md § Bootstrap: self-first seed ordering](Redundancy.md#bootstrap-self-first-seed-ordering). **Per-pair since Phase 6:** each application `Cluster`'s pair is its own Akka mesh, so a node's `SeedNodes` lists only itself (first) and its own pair partner (second) — never a node from another cluster's pair. |
-| `Roles` | string[] | `[]` | Cluster roles for this node. When empty, falls back to `OTOPCUA_ROLES`. Allowed values: `admin`, `driver`, `dev`, plus a per-cluster `cluster-{ClusterId}` role (e.g. `cluster-MAIN`, `cluster-SITE-A`) — see [Per-cluster mesh split (Phase 6)](#per-cluster-mesh-split-phase-6-cluster-clusterid-roles--splittopologytransportvalidator) below. |
+| `Roles` | string[] | `[]` | Cluster roles for this node. When empty, falls back to `OTOPCUA_ROLES` (see the note below). Allowed values: `admin`, `driver`, `dev`, plus a per-cluster `cluster-{ClusterId}` role (e.g. `cluster-MAIN`, `cluster-SITE-A`) — see [Per-cluster mesh split (Phase 6)](#per-cluster-mesh-split-phase-6-cluster-clusterid-roles--splittopologytransportvalidator) below. |
+
+> **`Cluster:Roles` and `OTOPCUA_ROLES` are two knobs for one thing, and only one of them is the Akka role list.** `OTOPCUA_ROLES` drives all of `Program.cs`'s conditional wiring (which subsystems mount); `Cluster:Roles` becomes the node's **gossiped Akka member roles**. Since Gitea #532 `AddOtOpcUaCluster` applies the documented fallback — an empty `Cluster:Roles` takes the env var — so setting only `OTOPCUA_ROLES` now works. Before that fix it did not, silently: the node joined the mesh carrying **no roles at all**, which reads as healthy locally and as *"no driver-role nodes are Up"* at central, and every deployment to it timed out ([`deployments/wonder-app-vd03-makino-z-34184.md`](deployments/wonder-app-vd03-makino-z-34184.md)).
+>
+> Setting `Cluster:Roles` explicitly is still the recommendation, because the two sources normalize differently: `Cluster:Roles` binds **verbatim** while the env path is **lower-cased** by `RoleParser.Parse`. Akka compares role names ordinally, so a redundant pair configured through *different* sources with a mixed-case `cluster-{ClusterId}` (e.g. `cluster-SITE-A` vs `cluster-site-a`) would gossip two different role names and elect two singletons. Configure both nodes of a pair the same way.
 
 > The full redundancy model (ServiceLevel tiers, split-brain, peer discovery) is in [`Redundancy.md`](Redundancy.md). The OPC UA peer-URI advertising lives in the `OpcUa:PeerApplicationUris` key above.
 
@@ -329,7 +333,7 @@ All names are read in this repo's source via `Environment.GetEnvironmentVariable
 
 | Variable | Read by | Effect / default |
 |---|---|---|
-| `OTOPCUA_ROLES` | `src/Server/ZB.MOM.WW.OtOpcUa.Host/Program.cs` (`RoleParser.Parse`) | Comma-separated cluster roles for the node (`admin`, `driver`, `dev`). Drives the conditional wiring and the per-role appsettings overlay. Used when `Cluster:Roles` is empty. |
+| `OTOPCUA_ROLES` | `src/Server/ZB.MOM.WW.OtOpcUa.Host/Program.cs` (`RoleParser.Parse`) and `AddOtOpcUaCluster`'s `AkkaClusterOptions` post-configure (`RoleParser.ResolveEffectiveRoles`) | Comma-separated cluster roles for the node (`admin`, `driver`, `dev`, `cluster-{ClusterId}`). Drives the conditional wiring and the per-role appsettings overlay, and — when `Cluster:Roles` is empty — the node's Akka member roles too. See the note under `Cluster:Roles` for why the two sources are not interchangeable. |
 | `OTOPCUA_CONFIG_CONNECTION` | `src/Core/ZB.MOM.WW.OtOpcUa.Configuration/DesignTimeDbContextFactory.cs` (design-time / `dotnet ef` only) | Read at **design time** by `DesignTimeDbContextFactory.cs` for `dotnet ef` migrations. At **runtime** the server resolves the connection string from `ConnectionStrings:ConfigDb` (env form: `ConnectionStrings__ConfigDb`) via `configuration.GetConnectionString("ConfigDb")` in `ServiceCollectionExtensions.cs` — `OTOPCUA_CONFIG_CONNECTION` appears there only as a hint in an error message, not via `GetEnvironmentVariable`. No credential is embedded in source. |
 | `ASPNETCORE_ENVIRONMENT` | ASP.NET host builder (framework) | Selects `appsettings.{Environment}.json` (e.g. `Development`). |
 

docs/deployments/wonder-app-vd03-makino-z-34184.md

@@ -56,6 +56,19 @@ now joins **UP with roles ADMIN+DRIVER** and deployments seal. Prior env backed
 > Product follow-up: either wire `OTOPCUA_ROLES` → `AkkaClusterOptions.Roles`, or bake `Cluster:Roles`
 > into the deploy template, so a node redeploy doesn't regress to role-less.
 
+> **RESOLVED 2026-08-01 (Gitea #532).** The first option shipped: `AddOtOpcUaCluster` post-configures
+> `AkkaClusterOptions`, so an empty `Cluster:Roles` now falls back to `OTOPCUA_ROLES` through
+> `RoleParser.ResolveEffectiveRoles`. A node in this box's original configuration would join **UP with
+> roles ADMIN+DRIVER** without the registry edit above, so a redeploy that drops the hand-added
+> `Cluster__Roles__0/1` no longer regresses to role-less. The `Cluster__Roles` entries are still worth
+> keeping — the two sources normalize case differently (see `docs/Configuration.md` → `Cluster:Roles`),
+> and an explicit list is the one that survives someone changing the env var for a different reason.
+>
+> Worth recording for the next incident of this shape: this was **documented behaviour that did not
+> exist**. `AkkaClusterOptions.Roles`' XML doc and `SplitTopologyTransportValidator` both described the
+> fallback, so anyone reading the code to diagnose this box would have concluded the roles were already
+> being applied and looked elsewhere.
+
 ## Live verification (OtOpcUa CLI client → server)
 
 `connect` + `browse` confirm the equipment + both tags are served at the node IDs above.

docs/security.md

@@ -337,16 +337,21 @@ until the tracking issue below is closed.
 
 **The four things blocking a wire-up** (all verified, none of them merely "call the evaluator"):
 
-1. **Raw-realm nodes have no representable scope.** `NodeHierarchyKind` has exactly one member,
-   `Equipment`. Raw NodeIds are `Folder→Driver→Device→TagGroup→Tag` RawPaths, which `NodeScope` cannot
-   express — yet the write gate is attached to raw tags. Roughly half the writable address space has
-   no scope to evaluate. This is a design decision, not wiring.
+1. ~~**Raw-realm nodes have no representable scope.**~~ **Closed by #520 stage 3.** `NodeScope` is now
+   `(ClusterId, Kind, Segments)` with a variable-length path, and `NodeHierarchyKind` carries both
+   `Uns` and `Raw`. The previous fixed-arity shape could not address a real raw tree at all — folder
+   chains and tag-group chains both nest without bound — so it silently capped at five levels and
+   mislabelled every one of them. Four `Raw*` scope kinds were appended for authoring.
 2. ~~**The identity carries roles, not groups.**~~ **Dissolved by #520 stage 2.** The column is now
    `NodeAcl.Principal` and the principal comes from the presented API key (or the reserved `anonymous`),
    not from a directory — so there is no group list to lose.
-3. **`PermissionTrieBuilder`'s `scopePaths` argument has no producer.** Without it every sub-cluster
-   grant lands in the builder's fallback bucket — the hazard its own comments warn about. It would have
-   to be derived from the artifact's UNS relations.
+3. ~~**`PermissionTrieBuilder`'s `scopePaths` argument has no producer.**~~ **Closed by #520 stage 3.**
+   `AclScopePathResolver` is that producer, built on both sides of the split — EF entities at the deploy
+   gate, artifact JSON on the node — and `scopePaths` is now a required argument with no fallback: an
+   unresolvable scope is **dropped with a diagnostic** rather than planted at a trie position the walk
+   can never reach. A scope resolves to *several* paths when one entity is reachable at several NodeIds
+   (a raw tag projected into N equipments has one raw path plus N UNS paths), because a grant that
+   covered only some of them would be bypassable through the one it missed.
 4. **No session lifecycle exists.** `UserAuthorizationState` has the freshness/staleness predicates but
    nothing in production constructs one per session. **Half-closed by stage 4:** the *generation* now
    exists and advances — `DataPlaneAuthorityState` stamps a monotonic `GenerationId` each time an
@@ -354,9 +359,23 @@ until the tracking issue below is closed.
    the stamping is stage 5's job, because until an enforcement seam reads it, a per-session state object
    would be constructed and never consulted.
 
-Two smaller inconsistencies inside the subsystem itself: `NodeAclScopeKind.FolderSegment` is offered in
-the authoring dropdown but the trie walker has no level to match it at, and `NodePermissions.AlarmRead`
-has no `OpcUaOperation` mapping, so it is grantable but unreachable.
+`NodeAclScopeKind.FolderSegment` is the retired v2 kind with no v3 entity behind it. It is still offered
+in the authoring dropdown (labelled retired), but it can never resolve, and both ends now say so
+specifically rather than reporting it as a missing id: the deploy gate rejects it with
+`NodeAclScopeKindRetired`, and the trie builder drops it with a `RetiredScopeKind` diagnostic (Gitea
+#533 — it used to arrive as `UnresolvedScope`, which sent an operator holding a legacy row hunting for a
+typo in an id that was never the problem). One inconsistency remains: `NodePermissions.AlarmRead` has no
+`OpcUaOperation` mapping, so it is grantable but unreachable.
+
+**String identity in this subsystem** (Gitea #533): **identifiers** — `ScopeId`, `ClusterId`,
+`Principal` — compare `OrdinalIgnoreCase`, because they are opaque handles whose spelling genuinely
+varies by source (a `ClusterId` arrives lower-cased through `OTOPCUA_ROLES` and verbatim through
+`Cluster:Roles`; a `ScopeId` is operator free-text until the stage-7 picker lands). **Path segments** —
+every level of a scope path, and therefore `PermissionTrieNode.Children` — compare `Ordinal`, because
+they are browse names and `Speed` / `speed` are two different nodes that can coexist under one device.
+The rule is stated in full on `AclScopeRef`. It matters most where the deploy gate and the node are fed
+from *different* snapshots, which is exactly the split `AclScopePathResolver` exists to bridge: case
+drift there would silently drop every grant on the affected scope.
 
 ### Hierarchy (design)