From 136234e7f23180745693279f28d4b5e502fe450f Mon Sep 17 00:00:00 2001
From: Joseph Doherty <dohejw01@gmail.com>
Date: Tue, 26 May 2026 04:27:19 -0400
Subject: [PATCH] feat(commons): add cluster/admin/diagnostics client
 interfaces

---
 .../Interfaces/IAdminOperationsClient.cs      | 13 ++++++++++++
 .../Interfaces/IClusterRoleInfo.cs            | 20 ++++++++++++++++++
 .../Interfaces/IFleetDiagnosticsClient.cs     | 12 +++++++++++
 .../Interfaces/NodeDiagnosticsSnapshot.cs     | 21 +++++++++++++++++++
 .../Interfaces/RoleLeaderChangedEventArgs.cs  | 10 +++++++++
 5 files changed, 76 insertions(+)
 create mode 100644 src/Core/ZB.MOM.WW.OtOpcUa.Commons/Interfaces/IAdminOperationsClient.cs
 create mode 100644 src/Core/ZB.MOM.WW.OtOpcUa.Commons/Interfaces/IClusterRoleInfo.cs
 create mode 100644 src/Core/ZB.MOM.WW.OtOpcUa.Commons/Interfaces/IFleetDiagnosticsClient.cs
 create mode 100644 src/Core/ZB.MOM.WW.OtOpcUa.Commons/Interfaces/NodeDiagnosticsSnapshot.cs
 create mode 100644 src/Core/ZB.MOM.WW.OtOpcUa.Commons/Interfaces/RoleLeaderChangedEventArgs.cs

diff --git a/src/Core/ZB.MOM.WW.OtOpcUa.Commons/Interfaces/IAdminOperationsClient.cs b/src/Core/ZB.MOM.WW.OtOpcUa.Commons/Interfaces/IAdminOperationsClient.cs
new file mode 100644
index 0000000..3a09986
--- /dev/null
+++ b/src/Core/ZB.MOM.WW.OtOpcUa.Commons/Interfaces/IAdminOperationsClient.cs
@@ -0,0 +1,13 @@
+using ZB.MOM.WW.OtOpcUa.Commons.Messages.Admin;
+
+namespace ZB.MOM.WW.OtOpcUa.Commons.Interfaces;
+
+/// <summary>
+/// Cluster-singleton-proxy client for the <c>AdminOperationsActor</c>. The Blazor UI calls
+/// this from any host (admin or driver role); the proxy routes the request to whichever node
+/// holds the admin singleton.
+/// </summary>
+public interface IAdminOperationsClient
+{
+    Task<StartDeploymentResult> StartDeploymentAsync(string createdBy, CancellationToken ct);
+}
diff --git a/src/Core/ZB.MOM.WW.OtOpcUa.Commons/Interfaces/IClusterRoleInfo.cs b/src/Core/ZB.MOM.WW.OtOpcUa.Commons/Interfaces/IClusterRoleInfo.cs
new file mode 100644
index 0000000..29c1dc1
--- /dev/null
+++ b/src/Core/ZB.MOM.WW.OtOpcUa.Commons/Interfaces/IClusterRoleInfo.cs
@@ -0,0 +1,20 @@
+using ZB.MOM.WW.OtOpcUa.Commons.Types;
+
+namespace ZB.MOM.WW.OtOpcUa.Commons.Interfaces;
+
+/// <summary>
+/// Live view of the local node's identity and the cluster's role topology. Implemented by
+/// <c>ClusterRoleInfo</c> in <c>OtOpcUa.Cluster</c>; consumed by everything that needs to
+/// distinguish admin-role vs driver-role members or react to role-leader changes (e.g. OPC UA
+/// ServiceLevel computation).
+/// </summary>
+public interface IClusterRoleInfo
+{
+    NodeId LocalNode { get; }
+    IReadOnlySet<string> LocalRoles { get; }
+    bool HasRole(string role);
+    IReadOnlyList<NodeId> MembersWithRole(string role);
+    NodeId? RoleLeader(string role);
+
+    event EventHandler<RoleLeaderChangedEventArgs>? RoleLeaderChanged;
+}
diff --git a/src/Core/ZB.MOM.WW.OtOpcUa.Commons/Interfaces/IFleetDiagnosticsClient.cs b/src/Core/ZB.MOM.WW.OtOpcUa.Commons/Interfaces/IFleetDiagnosticsClient.cs
new file mode 100644
index 0000000..cab512a
--- /dev/null
+++ b/src/Core/ZB.MOM.WW.OtOpcUa.Commons/Interfaces/IFleetDiagnosticsClient.cs
@@ -0,0 +1,12 @@
+using ZB.MOM.WW.OtOpcUa.Commons.Types;
+
+namespace ZB.MOM.WW.OtOpcUa.Commons.Interfaces;
+
+/// <summary>
+/// Per-node diagnostics fetched on demand. Implemented in Phase 8 (AdminUI/Runtime wiring)
+/// over an Akka request/response — the diagnostics actor lives on the target driver node.
+/// </summary>
+public interface IFleetDiagnosticsClient
+{
+    Task<NodeDiagnosticsSnapshot> GetDiagnosticsAsync(NodeId nodeId, CancellationToken ct);
+}
diff --git a/src/Core/ZB.MOM.WW.OtOpcUa.Commons/Interfaces/NodeDiagnosticsSnapshot.cs b/src/Core/ZB.MOM.WW.OtOpcUa.Commons/Interfaces/NodeDiagnosticsSnapshot.cs
new file mode 100644
index 0000000..e31b62f
--- /dev/null
+++ b/src/Core/ZB.MOM.WW.OtOpcUa.Commons/Interfaces/NodeDiagnosticsSnapshot.cs
@@ -0,0 +1,21 @@
+using ZB.MOM.WW.OtOpcUa.Commons.Types;
+
+namespace ZB.MOM.WW.OtOpcUa.Commons.Interfaces;
+
+public sealed record DriverInstanceDiagnostics(
+    Guid DriverInstanceId,
+    string Name,
+    string State,
+    int ConnectedDevices,
+    int FaultedDevices,
+    DateTime LastChangeUtc);
+
+/// <summary>
+/// Per-node diagnostics returned by <c>IFleetDiagnosticsClient</c>. Populated by the node's
+/// local <c>DriverHostActor</c> via a request/response over Akka.
+/// </summary>
+public sealed record NodeDiagnosticsSnapshot(
+    NodeId NodeId,
+    RevisionHash? CurrentRevision,
+    IReadOnlyList<DriverInstanceDiagnostics> Drivers,
+    DateTime AsOfUtc);
diff --git a/src/Core/ZB.MOM.WW.OtOpcUa.Commons/Interfaces/RoleLeaderChangedEventArgs.cs b/src/Core/ZB.MOM.WW.OtOpcUa.Commons/Interfaces/RoleLeaderChangedEventArgs.cs
new file mode 100644
index 0000000..50fb8f1
--- /dev/null
+++ b/src/Core/ZB.MOM.WW.OtOpcUa.Commons/Interfaces/RoleLeaderChangedEventArgs.cs
@@ -0,0 +1,10 @@
+using ZB.MOM.WW.OtOpcUa.Commons.Types;
+
+namespace ZB.MOM.WW.OtOpcUa.Commons.Interfaces;
+
+public sealed class RoleLeaderChangedEventArgs : EventArgs
+{
+    public required string Role { get; init; }
+    public required NodeId? PreviousLeader { get; init; }
+    public required NodeId? NewLeader { get; init; }
+}