refactor(host): CentralSingletonRegistrar -> SingletonRegistrar with optional role scope — unblocks site-singleton drains (plan R2-01 T10)

src/ZB.MOM.WW.ScadaBridge.Host/Actors/AkkaHostedService.cs

@@ -456,14 +456,14 @@ akka {{
         var outboxAuditWriter = _serviceProvider
             .GetRequiredService<ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Services.ICentralAuditWriter>();
 
-        // All central singletons below are created through CentralSingletonRegistrar.Start,
+        // All central singletons below are created through SingletonRegistrar.Start,
         // which pins the actor to the active central node (ClusterSingletonManager), exposes a
         // stable address (ClusterSingletonProxy), and — crucially — registers a PhaseClusterLeave
         // GracefulStop drain task so an in-flight EF write drains before handover (review 01
         // [Medium]: notification-outbox and audit-log-ingest previously had NO drain task). Names
-        // are unchanged ({name}-singleton / {name}-proxy). The two SITE singletons stay
+        // are unchanged ({name}-singleton / {name}-proxy). Site singletons use the same
-        // hand-rolled below because they are role-scoped (.WithRole(siteRole)).
+        // registrar with `role: siteRole` (Task 11 / round-2 N5).
-        var outbox = CentralSingletonRegistrar.Start(
+        var outbox = SingletonRegistrar.Start(
             _actorSystem!, "notification-outbox",
             Props.Create(() => new ZB.MOM.WW.ScadaBridge.NotificationOutbox.NotificationOutboxActor(
                 _serviceProvider,
@@ -496,7 +496,7 @@ akka {{
         var auditIngestLogger = _serviceProvider.GetRequiredService<ILoggerFactory>()
             .CreateLogger<ZB.MOM.WW.ScadaBridge.AuditLog.Central.AuditLogIngestActor>();
 
-        var auditIngest = CentralSingletonRegistrar.Start(
+        var auditIngest = SingletonRegistrar.Start(
             _actorSystem!, "audit-log-ingest",
             Props.Create(() => new ZB.MOM.WW.ScadaBridge.AuditLog.Central.AuditLogIngestActor(
                 _serviceProvider,
@@ -561,7 +561,7 @@ akka {{
         var siteCallAuditOptions = _serviceProvider
             .GetRequiredService<IOptions<ZB.MOM.WW.ScadaBridge.SiteCallAudit.SiteCallAuditOptions>>().Value;
 
-        var siteCallAudit = CentralSingletonRegistrar.Start(
+        var siteCallAudit = SingletonRegistrar.Start(
             _actorSystem!, "site-call-audit",
             Props.Create(() => new ZB.MOM.WW.ScadaBridge.SiteCallAudit.SiteCallAuditActor(
                 _serviceProvider,
@@ -606,7 +606,7 @@ akka {{
         var auditLogOptions = _serviceProvider
             .GetRequiredService<IOptions<ZB.MOM.WW.ScadaBridge.AuditLog.Configuration.AuditLogOptions>>();
 
-        CentralSingletonRegistrar.Start(
+        SingletonRegistrar.Start(
             _actorSystem!, "audit-log-purge",
             Props.Create(() => new ZB.MOM.WW.ScadaBridge.AuditLog.Central.AuditLogPurgeActor(
                 _serviceProvider,
@@ -629,7 +629,7 @@ akka {{
         var auditReconClient = _serviceProvider
             .GetRequiredService<ZB.MOM.WW.ScadaBridge.AuditLog.Central.IPullAuditEventsClient>();
 
-        CentralSingletonRegistrar.Start(
+        SingletonRegistrar.Start(
             _actorSystem!, "site-audit-reconciliation",
             Props.Create(() => new ZB.MOM.WW.ScadaBridge.AuditLog.Central.SiteAuditReconciliationActor(
                 auditReconSites,
@@ -660,7 +660,7 @@ akka {{
         var kpiHistoryLogger = _serviceProvider.GetRequiredService<ILoggerFactory>()
             .CreateLogger<ZB.MOM.WW.ScadaBridge.KpiHistory.KpiHistoryRecorderActor>();
 
-        CentralSingletonRegistrar.Start(
+        SingletonRegistrar.Start(
             _actorSystem!, "kpi-history-recorder",
             Props.Create(() => new ZB.MOM.WW.ScadaBridge.KpiHistory.KpiHistoryRecorderActor(
                 _serviceProvider,
@@ -686,7 +686,7 @@ akka {{
         var pendingPurgeCommunicationOptions =
             _serviceProvider.GetRequiredService<IOptions<CommunicationOptions>>();
 
-        CentralSingletonRegistrar.Start(
+        SingletonRegistrar.Start(
             _actorSystem!, "pending-deployment-purge",
             Props.Create(() => new PendingDeploymentPurgeActor(
                 _serviceProvider,

src/ZB.MOM.WW.ScadaBridge.Host/Actors/SingletonRegistrar.cs

@@ -5,21 +5,24 @@ using Microsoft.Extensions.Logging;
 namespace ZB.MOM.WW.ScadaBridge.Host.Actors;
 
 /// <summary>
-/// Registers a central cluster singleton with the canonical naming scheme
+/// Registers a cluster singleton with the canonical naming scheme
 /// (<c>{name}-singleton</c> / <c>{name}-proxy</c>), a PoisonPill termination
 /// message, and a PhaseClusterLeave drain task that GracefulStops the manager
-/// so in-flight EF work completes before handover. Extracted from five
+/// so in-flight EF (central) or SQLite (site) work completes before handover.
-/// copy-pasted ~60-line blocks (review 01 [Low]) whose drift left the two
+/// Extracted from copy-pasted ~60-line blocks (review 01 [Low]) whose drift
-/// busiest singletons (notification-outbox, audit-log-ingest) without drain
+/// left the two busiest singletons (notification-outbox, audit-log-ingest)
-/// tasks (review 01 [Medium]).
+/// without drain tasks (review 01 [Medium]). The optional <c>role</c> maps to
+/// <see cref="ClusterSingletonManagerSettings"/>/<see cref="ClusterSingletonProxySettings"/>
+/// <c>.WithRole</c>, so role-scoped site singletons get the same drain
+/// (review 01 round-2 N5).
 /// </summary>
-internal static class CentralSingletonRegistrar
+internal static class SingletonRegistrar
 {
     internal sealed record Handle(IActorRef Manager, IActorRef Proxy);
 
     /// <summary>
-    /// Creates the <see cref="ClusterSingletonManager"/> and proxy for a central
+    /// Creates the <see cref="ClusterSingletonManager"/> and proxy for a cluster
-    /// cluster singleton under the canonical naming scheme, and registers a
+    /// singleton under the canonical naming scheme, and registers a
     /// PhaseClusterLeave drain task that GracefulStops the manager on shutdown.
     /// </summary>
     /// <param name="system">The actor system to register the singleton on.</param>
@@ -27,19 +30,24 @@ internal static class CentralSingletonRegistrar
     /// <param name="singletonProps">The <see cref="Props"/> used to create the singleton's managed actor.</param>
     /// <param name="logger">Logger used to report drain progress/failures.</param>
     /// <param name="drainTimeout">Maximum time to wait for the drain task to complete; defaults to 10 seconds.</param>
+    /// <param name="role">Optional cluster role to scope the singleton to (applied to both the manager and proxy settings).</param>
     /// <returns>A <see cref="Handle"/> carrying the singleton manager and proxy actor refs.</returns>
     internal static Handle Start(
         ActorSystem system,
         string name,
         Props singletonProps,
         ILogger logger,
-        TimeSpan? drainTimeout = null)
+        TimeSpan? drainTimeout = null,
+        string? role = null)
     {
+        var managerSettings = ClusterSingletonManagerSettings.Create(system).WithSingletonName(name);
+        if (role is not null) managerSettings = managerSettings.WithRole(role);
+
         var manager = system.ActorOf(
             ClusterSingletonManager.Props(
                 singletonProps,
                 PoisonPill.Instance,
-                ClusterSingletonManagerSettings.Create(system).WithSingletonName(name)),
+                managerSettings),
             $"{name}-singleton");
 
         var timeout = drainTimeout ?? TimeSpan.FromSeconds(10);
@@ -61,10 +69,13 @@ internal static class CentralSingletonRegistrar
                 return Akka.Done.Instance;
             });
 
+        var proxySettings = ClusterSingletonProxySettings.Create(system).WithSingletonName(name);
+        if (role is not null) proxySettings = proxySettings.WithRole(role);
+
         var proxy = system.ActorOf(
             ClusterSingletonProxy.Props(
                 $"/user/{name}-singleton",
-                ClusterSingletonProxySettings.Create(system).WithSingletonName(name)),
+                proxySettings),
             $"{name}-proxy");
 
         return new Handle(manager, proxy);

tests/ZB.MOM.WW.ScadaBridge.Host.Tests/CoordinatedShutdownTests.cs

@@ -51,9 +51,9 @@ public class CoordinatedShutdownTests
 
         // Review 01 [Medium]: notification-outbox and audit-log-ingest were the
         // only central singletons WITHOUT a cluster-leave drain task. All seven
-        // now go through CentralSingletonRegistrar.Start, which always adds the
+        // now go through SingletonRegistrar.Start, which always adds the
         // PhaseClusterLeave GracefulStop drain.
-        Assert.Contains("CentralSingletonRegistrar.Start(", content);
+        Assert.Contains("SingletonRegistrar.Start(", content);
         foreach (var name in new[] { "notification-outbox", "audit-log-ingest", "site-call-audit",
                                      "audit-log-purge", "site-audit-reconciliation",
                                      "kpi-history-recorder", "pending-deployment-purge" })

tests/ZB.MOM.WW.ScadaBridge.Host.Tests/SingletonRegistrarTests.cs

@@ -5,7 +5,7 @@ using ZB.MOM.WW.ScadaBridge.Host.Actors;
 
 namespace ZB.MOM.WW.ScadaBridge.Host.Tests;
 
-public class CentralSingletonRegistrarTests
+public class SingletonRegistrarTests
 {
     private sealed class EchoActor : ReceiveActor
     {
@@ -16,7 +16,7 @@ public class CentralSingletonRegistrarTests
     public async Task Start_CreatesManagerAndProxy_WithCanonicalNames_AndDrainTask()
     {
         using var system = CreateSingleNodeClusterSystem();
-        var handle = CentralSingletonRegistrar.Start(
+        var handle = SingletonRegistrar.Start(
             system, "test-widget", Props.Create(() => new EchoActor()),
             NullLogger.Instance, drainTimeout: TimeSpan.FromSeconds(2));
 
@@ -36,6 +36,25 @@ public class CentralSingletonRegistrarTests
         Assert.True(handle.Manager.IsNobody() || system.WhenTerminated.IsCompleted);
     }
 
+    [Fact]
+    public async Task Start_WithRoleScope_CreatesRoleScopedSingleton_ThatAnswers()
+    {
+        // Round-2 N5: role scoping is what kept the two SITE singletons
+        // (deployment-manager, event-log-handler) hand-rolled and drain-less.
+        using var system = CreateSingleNodeClusterSystem(); // roles = ["Central"]
+        var handle = SingletonRegistrar.Start(
+            system, "role-widget", Props.Create(() => new EchoActor()),
+            NullLogger.Instance, drainTimeout: TimeSpan.FromSeconds(2), role: "Central");
+
+        Assert.EndsWith("/user/role-widget-singleton", handle.Manager.Path.ToString());
+        Assert.EndsWith("/user/role-widget-proxy", handle.Proxy.Path.ToString());
+
+        // The node holds the role => manager instantiates the singleton and
+        // the role-scoped proxy resolves it.
+        var echo = await handle.Proxy.Ask<string>("hi", TimeSpan.FromSeconds(20));
+        Assert.Equal("hi", echo);
+    }
+
     private static ActorSystem CreateSingleNodeClusterSystem()
     {
         var port = FreePort();