docs: one role authority — precedence, normalization, and the overlay invariant (R3-04)

CLAUDE.md

@@ -435,6 +435,50 @@ Assert the **effective** cluster config off a running `ActorSystem` (as `SplitBr
 
 See `docs/Redundancy.md` §"Per-cluster meshes (Phase 6)", `docs/Configuration.md` §"Per-cluster mesh split (Phase 6)", and `docs/plans/2026-07-24-mesh-phase6-partition-and-colocation.md`.
 
+## Role authority (`EffectiveRoles`)
+
+**A node's roles are resolved in exactly one place** (archreview R3-04, closing 01/S-12 = 03/C5 and
+01/C-9): `EffectiveRoles.Resolve` (`ZB.MOM.WW.OtOpcUa.Cluster`), with one precedence —
+`Cluster:Roles` when non-empty, else `OTOPCUA_ROLES`, else empty — and two-layer normalization: a
+plain role (`admin`/`driver`/`dev`) is trimmed and lower-cased, but a cluster role's ClusterId suffix
+(`cluster-SITE-A`) is kept verbatim, because lower-casing it would rename the Akka role of a running
+deployment. An unknown role from **either** source fails host start. `Program.cs` resolves one
+`EffectiveRoles` instance at the top of the composition root and registers it as a singleton; that
+SAME instance drives both the conditional host wiring (`hasAdmin`/`hasDriver`) and
+`AkkaClusterOptions.Roles` (what Akka gossips) — there is no second derivation for the two to
+disagree about, which is why no runtime "do the views agree" assert exists. Before this, `Program.cs`
+read `OTOPCUA_ROLES` only, so a node configured solely through `Cluster:Roles` gossiped the right
+Akka roles while `Program.cs`'s own wiring mounted none of them — the inverse of the pre-#532 field
+incident (`docs/deployments/wonder-app-vd03-makino-z-34184.md`).
+
+- **A role overlay may not itself set `Cluster:Roles`.** Roles are resolved *before* the per-role
+  appsettings overlay loads (the overlay's filename depends on the answer), so a later layer changing
+  `Cluster:Roles` would leave the bound options disagreeing with the registered instance.
+  `AkkaClusterOptionsValidator` fails host start if this ever happens, naming both views — a no-op
+  today since none of the four shipped overlays carries a `Cluster` section.
+- **Both sources set to different normalized role sets logs a Warning** at boot (`Cluster:Roles`
+  still wins outright) — the boot banner also names which source won (`source=Configured` /
+  `Environment` / `None`).
+- **`RoleParser.GossipedRolesHave`** (case-insensitive) is defence in depth at the handful of
+  production sites that read LIVE GOSSIP directly (`Member.Roles`) rather than through
+  `EffectiveRoles` — a peer running an older, pre-R3-04 build can still gossip a miscased plain role
+  during a rolling upgrade. ⚠️ **Known residual, not closed by R3-04:**
+  `RedundancyStateActor.SelectOldestUpMemberOfRole`/`SelectDriverPrimary` delegate to
+  `ZB.MOM.WW.Health.Akka`'s `ClusterActiveNode.OldestUpMember`, which matches via Akka's OWN ordinal
+  `Member.HasRole` — not this repo's to patch, the same class of "not ours to change" carve-out as
+  `ClusterSingletonOptions.Role`. A pair where every member is on a fixed build can no longer gossip
+  a miscased role at all (normalization happens before gossip), so this only bites a genuinely mixed
+  fixed/pre-fix rolling-upgrade window.
+- **`RoleAuthorityGuardTests`** (`tests/Core/ZB.MOM.WW.OtOpcUa.Cluster.Tests/`) is the enforcement:
+  a source scan failing on any production file outside `EffectiveRoles.cs`/`RoleParser.cs` that reads
+  `OTOPCUA_ROLES`, `Cluster:Roles` as code, or declares a bare `"admin"`/`"driver"`/`"dev"` literal —
+  with a small, reasoned allow-list for the handful of genuinely unrelated domain uses of those same
+  English words (a raw-tree node-kind label, a Sql driver's own JSON marker, an LDAP-derived AdminUI
+  RBAC role).
+
+See `docs/Configuration.md` §`Roles`, `docs/ServiceHosting.md` §"Role gating", and
+`archreview/plans/R3-04-one-role-authority-plan.md`.
+
 ## Mesh command transport (`MeshTransport`)
 
 **The Akka `ClusterClient` transport described in this section's earlier history is DELETED**