fix(secrets): root-cause + fix the Akka replicator's hosted-process DI deadlock (0.2.2)

Closes the defect in scadaproj#1. The hang was never Akka: the package's DI
wiring closed a circular singleton dependency the container cannot see through
factory lambdas — ISecretStore (ReplicatingSecretStore decorator) ->
ISecretReplicator -> SecretReplicationActorProvider -> ISecretCacheInvalidator
-> DefaultSecretResolver -> ISecretStore. Resolution recurses around the loop
until MS.DI's StackGuard hops it onto a fresh thread-pool thread, which then
blocks forever on a singleton call-site lock the first thread still holds:
a silent permanent hang instead of a stack overflow. Managed stacks from
dotnet-dump show the repeating cycle and both parked threads; both candidate
causes in the issue (DistributedPubSub.Get vs the Lazy lock, missing
Akka.Cluster.Tools HOCON) are disproven — the actor constructor was never
reached, and the deadlock reproduces on a single non-clustered node.

Fix: defer the one cycle-closing edge. The provider now gets a
DeferredSecretCacheInvalidator that resolves the real invalidator on first
eviction — which only happens when a replicated row is applied, strictly after
graph resolution. Severing the edge instead is wrong: a null-invalidator
experiment ran the live gate at 5/6, with deleted secrets still resolving on
the peer. The SqlServer package never had the cycle (its replicator chain
never touches the invalidator), which is why the hub gate always passed.

Verified: live 2-node convergence gate now 6/6 (was: infinite hang), including
the delete-visibility check that proves the deferred invalidator really evicts.
New HostedProcessResolutionTests builds the graph as a host does (container-
registered ActorSystem, hosted services, watchdogged resolves) and fails on
0.2.1; DeferredSecretCacheInvalidatorTests pins the wrapper contract. Full
suite 180 passed / 0 failed / 15 skipped (env-gated live SQL).

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

ZB.MOM.WW.Secrets/Directory.Build.props

@@ -5,7 +5,7 @@
     <Nullable>enable</Nullable>
     <ImplicitUsings>enable</ImplicitUsings>
     <LangVersion>latest</LangVersion>
-    <Version>0.2.1</Version>
+    <Version>0.2.2</Version>
     <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
     <PackageReadmeFile>README.md</PackageReadmeFile>
   </PropertyGroup>

ZB.MOM.WW.Secrets/src/ZB.MOM.WW.Secrets.Replicator.AkkaDotNet/DependencyInjection/AkkaSecretsServiceCollectionExtensions.cs

@@ -69,10 +69,17 @@ public static class AkkaSecretsServiceCollectionExtensions
         // The actor is created lazily on first use rather than at registration: the ActorSystem is
         // typically registered by the application AFTER this call, and a cluster node may also not be
         // ready to join at the moment the container is built.
+        //
+        // The invalidator MUST stay deferred (scadaproj#1): it is the resolver, the resolver reads
+        // ISecretStore, and ISecretStore is the ReplicatingSecretStore decorator registered below —
+        // resolving it here closes a singleton cycle the container cannot detect through factory
+        // lambdas, and every hosted process then deadlocks at startup inside the container's
+        // resolution locks. DeferredSecretCacheInvalidator waits until the first eviction, which
+        // can only happen after the graph has finished resolving.
         services.TryAddSingleton<SecretReplicationActorProvider>(sp => new SecretReplicationActorProvider(
             sp.GetRequiredService<ActorSystem>(),
             sp.GetRequiredService<SqliteSecretStore>(),
-            sp.GetService<ISecretCacheInvalidator>(),
+            new DeferredSecretCacheInvalidator(sp.GetService<ISecretCacheInvalidator>),
             sp.GetRequiredService<IOptions<AkkaSecretsReplicationOptions>>().Value));
 
         // MUST be registered BEFORE AddZbSecrets. That call does

ZB.MOM.WW.Secrets/src/ZB.MOM.WW.Secrets.Replicator.AkkaDotNet/DependencyInjection/DeferredSecretCacheInvalidator.cs

@@ -0,0 +1,39 @@
+using ZB.MOM.WW.Secrets.Abstractions;
+
+namespace ZB.MOM.WW.Secrets.Replicator.AkkaDotNet.DependencyInjection;
+
+/// <summary>
+/// Resolves the real <see cref="ISecretCacheInvalidator"/> on first eviction instead of at
+/// construction, so the replication graph can be wired without closing a dependency cycle.
+/// </summary>
+/// <remarks>
+/// <para>
+/// This deferral is load-bearing, not an optimization (scadaproj#1). The invalidator is the
+/// resolver, the resolver reads through <c>ISecretStore</c>, and with replication registered
+/// <c>ISecretStore</c> is the <c>ReplicatingSecretStore</c> decorator whose replicator owns this
+/// node's actor — so resolving the invalidator eagerly inside the actor provider's factory closes
+/// a singleton cycle the container cannot see through factory lambdas. Resolution then recurses
+/// until MS.DI's <c>StackGuard</c> hops it onto another thread, which deadlocks on a call-site
+/// lock the first thread holds: any host resolving the graph hangs at startup, silently and
+/// permanently.
+/// </para>
+/// <para>
+/// Deferring to first eviction is sufficient because evictions only happen when a replicated row
+/// is applied — strictly after the graph has finished resolving, at which point every singleton on
+/// the former cycle is already materialized and the lookup completes without re-entering the
+/// container's resolution locks.
+/// </para>
+/// </remarks>
+/// <param name="resolve">
+/// Lookup for the real invalidator; returns <c>null</c> when the application registered none.
+/// </param>
+internal sealed class DeferredSecretCacheInvalidator(Func<ISecretCacheInvalidator?> resolve)
+    : ISecretCacheInvalidator
+{
+    private readonly Lazy<ISecretCacheInvalidator?> _inner = new(
+        resolve ?? throw new ArgumentNullException(nameof(resolve)),
+        LazyThreadSafetyMode.ExecutionAndPublication);
+
+    /// <inheritdoc />
+    public void Invalidate(SecretName name) => _inner.Value?.Invalidate(name);
+}

ZB.MOM.WW.Secrets/tests/ZB.MOM.WW.Secrets.Replicator.AkkaDotNet.Tests/DependencyInjection/AddZbSecretsAkkaReplicationTests.cs

@@ -25,12 +25,14 @@ namespace ZB.MOM.WW.Secrets.Replicator.AkkaDotNet.Tests.DependencyInjection;
 /// the other, so the gap is closed here.
 /// </para>
 /// <para>
-/// These assert against the <see cref="IServiceCollection"/> rather than a built provider on
+/// These assert against the <see cref="IServiceCollection"/> because the 0.2.0 defect was entirely
-/// purpose. Resolving <c>ISecretReplicator</c> eagerly spawns the replication actor, whose
+/// about which descriptor wins, and the descriptor is where it is visible. Resolution through a
-/// <c>PreStart</c> calls <c>DistributedPubSub.Get(...)</c>; that requires a joined cluster, so a
+/// BUILT provider — where the scadaproj#1 singleton-cycle deadlock lived — is covered by
-/// provider-based test would need a real single-node cluster and would hang without one. The
+/// <see cref="HostedProcessResolutionTests"/>, and end-to-end actor behaviour by
-/// defect was entirely about which descriptor wins, and the descriptor is where it is visible.
+/// <c>TwoNodeClusterReplicationTests</c>. (An earlier revision of this comment claimed a
-/// End-to-end actor behaviour is already covered by <c>TwoNodeClusterReplicationTests</c>.
+/// provider-based test was impossible because <c>DistributedPubSub.Get</c> needs a joined
+/// cluster; the hang it was avoiding was actually that DI deadlock, and a single self-joined
+/// node is all the cluster the actor needs.)
 /// </para>
 /// </summary>
 public sealed class AddZbSecretsAkkaReplicationTests

ZB.MOM.WW.Secrets/tests/ZB.MOM.WW.Secrets.Replicator.AkkaDotNet.Tests/DependencyInjection/DeferredSecretCacheInvalidatorTests.cs

@@ -0,0 +1,75 @@
+using ZB.MOM.WW.Secrets.Abstractions;
+using ZB.MOM.WW.Secrets.Replicator.AkkaDotNet.DependencyInjection;
+
+namespace ZB.MOM.WW.Secrets.Replicator.AkkaDotNet.Tests.DependencyInjection;
+
+/// <summary>
+/// The deferred invalidator exists to break the scadaproj#1 dependency cycle, which makes it a
+/// pass-through that could silently pass nothing through — the exact failure mode (inert seam,
+/// green suite) this library has shipped before. These tests pin the two halves of its contract:
+/// nothing resolves before the first eviction, and evictions actually reach the real invalidator.
+/// </summary>
+public sealed class DeferredSecretCacheInvalidatorTests
+{
+    private sealed class RecordingInvalidator : ISecretCacheInvalidator
+    {
+        public List<SecretName> Evicted { get; } = [];
+
+        public void Invalidate(SecretName name) => Evicted.Add(name);
+    }
+
+    [Fact]
+    public void Construction_does_not_resolve_the_inner_invalidator()
+    {
+        // THE point of the type: resolving eagerly is what closed the singleton cycle and hung
+        // every hosted process at startup.
+        bool resolved = false;
+
+        _ = new DeferredSecretCacheInvalidator(() =>
+        {
+            resolved = true;
+            return null;
+        });
+
+        Assert.False(resolved);
+    }
+
+    [Fact]
+    public void Invalidate_forwards_to_the_resolved_invalidator()
+    {
+        var inner = new RecordingInvalidator();
+        var deferred = new DeferredSecretCacheInvalidator(() => inner);
+        var name = new SecretName("gate/alpha");
+
+        deferred.Invalidate(name);
+
+        Assert.Equal([name], inner.Evicted);
+    }
+
+    [Fact]
+    public void The_lookup_runs_once_and_the_instance_is_reused()
+    {
+        int lookups = 0;
+        var inner = new RecordingInvalidator();
+        var deferred = new DeferredSecretCacheInvalidator(() =>
+        {
+            lookups++;
+            return inner;
+        });
+
+        deferred.Invalidate(new SecretName("gate/alpha"));
+        deferred.Invalidate(new SecretName("gate/beta"));
+
+        Assert.Equal(1, lookups);
+        Assert.Equal(2, inner.Evicted.Count);
+    }
+
+    [Fact]
+    public void A_null_resolution_means_evictions_are_no_ops()
+    {
+        // Mirrors the reconciler's own contract: no invalidator registered, nothing to evict.
+        var deferred = new DeferredSecretCacheInvalidator(() => null);
+
+        deferred.Invalidate(new SecretName("gate/alpha"));
+    }
+}

ZB.MOM.WW.Secrets/tests/ZB.MOM.WW.Secrets.Replicator.AkkaDotNet.Tests/DependencyInjection/HostedProcessResolutionTests.cs

@@ -0,0 +1,153 @@
+using Akka.Actor;
+using Akka.Cluster;
+using Akka.Configuration;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+using ZB.MOM.WW.Secrets.Abstractions;
+using ZB.MOM.WW.Secrets.Replication;
+using ZB.MOM.WW.Secrets.Replicator.AkkaDotNet.DependencyInjection;
+
+namespace ZB.MOM.WW.Secrets.Replicator.AkkaDotNet.Tests.DependencyInjection;
+
+/// <summary>
+/// Builds the replication graph the way a real application host does — container-registered
+/// <see cref="ActorSystem"/>, hosted services started, services resolved from the built provider —
+/// and asserts resolution actually completes.
+/// </summary>
+/// <remarks>
+/// <para>
+/// This is the regression test for scadaproj#1. The 0.2.x graph had a circular singleton
+/// dependency reachable only through the container: <c>ISecretStore</c> (the
+/// <c>ReplicatingSecretStore</c> decorator) → <c>ISecretReplicator</c> →
+/// <c>SecretReplicationActorProvider</c> → <c>ISecretCacheInvalidator</c> →
+/// <c>DefaultSecretResolver</c> → <c>ISecretStore</c>. Every edge is an opaque factory lambda, so
+/// the container cannot detect the cycle statically; at runtime the resolution recurses until
+/// MS.DI's <c>StackGuard</c> moves it onto a fresh thread-pool thread, which then blocks forever on
+/// a singleton call-site lock the first thread still holds. The symptom was a silent, permanent
+/// hang — not a stack overflow, not an exception — which is why every direct-construction test
+/// passed while any hosted process froze at startup.
+/// </para>
+/// <para>
+/// The suite's other cluster tests construct the actor with <c>system.ActorOf</c> directly and can
+/// never see this defect. Nothing here may resolve the affected services before the assertions do.
+/// </para>
+/// </remarks>
+public sealed class HostedProcessResolutionTests : IAsyncLifetime
+{
+    // Generous next to the milliseconds a healthy resolve takes, tiny next to CI noise: on
+    // regression the resolve NEVER completes, so the only cost of margin is this test's runtime.
+    private static readonly TimeSpan ResolveBudget = TimeSpan.FromSeconds(20);
+
+    private readonly string _dbPath =
+        Path.Combine(Path.GetTempPath(), $"zb-hosted-di-{Guid.NewGuid():N}.db");
+
+    private ActorSystem _system = null!;
+    private ServiceProvider _provider = null!;
+
+    public async Task InitializeAsync()
+    {
+        // A single self-joined cluster node: `actor.provider = cluster` is what the replication
+        // actor's DistributedPubSub mediator needs, and joining makes the rig an honest miniature
+        // of an app node rather than a special case.
+        _system = ActorSystem.Create("zb-secrets-cluster", ConfigurationFactory.ParseString("""
+            akka {
+              loglevel = WARNING
+              actor.provider = cluster
+              remote.dot-netty.tcp {
+                hostname = "127.0.0.1"
+                public-hostname = "127.0.0.1"
+                port = 0
+              }
+            }
+            """).WithFallback(AkkaSecretsReplication.SerializationConfig));
+
+        Cluster cluster = Cluster.Get(_system);
+        cluster.Join(cluster.SelfAddress);
+
+        DateTime deadline = DateTime.UtcNow + TimeSpan.FromSeconds(20);
+        while (cluster.State.Members.All(m => m.Status != MemberStatus.Up))
+        {
+            if (DateTime.UtcNow > deadline)
+            {
+                throw new TimeoutException("Single-node cluster never reached Up.");
+            }
+
+            await Task.Delay(100);
+        }
+
+        IConfigurationRoot config = new ConfigurationBuilder()
+            .AddInMemoryCollection(new Dictionary<string, string?>
+            {
+                ["Secrets:SqlitePath"] = _dbPath,
+                ["Secrets:RunMigrationsOnStartup"] = "true",
+                ["Secrets:Replication:AnnounceInterval"] = "00:00:30",
+            })
+            .Build();
+
+        var services = new ServiceCollection();
+        services.AddLogging();
+        services.AddSingleton(_system);
+        services.AddZbSecretsAkkaReplication(config, "Secrets", "Secrets:Replication");
+        _provider = services.BuildServiceProvider();
+
+        // Started exactly as a host would, BEFORE anything resolves the replicated store — the
+        // order OtOpcUa's startup follows, and the order under which the deadlock was reproduced.
+        foreach (IHostedService hosted in _provider.GetServices<IHostedService>())
+        {
+            await hosted.StartAsync(CancellationToken.None);
+        }
+    }
+
+    [Fact]
+    public async Task Resolving_the_replicated_graph_through_the_container_completes()
+    {
+        // One test covers all three entry points IN this order: the store is the edge OtOpcUa's
+        // startup hook actually resolves, the replicator is the narrowest reproduction of the
+        // hang, and the resolver closes the loop from the invalidator's side. Split into separate
+        // facts, each would rebuild the rig only to hit the same three singletons.
+        ISecretStore store = await ResolveWithinBudgetAsync(
+            sp => sp.GetRequiredService<ISecretStore>(), nameof(ISecretStore));
+        ISecretReplicator replicator = await ResolveWithinBudgetAsync(
+            sp => sp.GetRequiredService<ISecretReplicator>(), nameof(ISecretReplicator));
+        ISecretResolver resolver = await ResolveWithinBudgetAsync(
+            sp => sp.GetRequiredService<ISecretResolver>(), nameof(ISecretResolver));
+
+        Assert.IsType<ReplicatingSecretStore>(store);
+        Assert.IsType<AkkaSecretReplicator>(replicator);
+        Assert.NotNull(resolver);
+    }
+
+    private async Task<T> ResolveWithinBudgetAsync<T>(
+        Func<IServiceProvider, T> resolve, string label)
+    {
+        // The failure mode under test is an infinite wait inside the container, so the resolve
+        // runs on the pool with a watchdog. On regression the worker thread is unrecoverable —
+        // acceptable in a test process that is about to exit, and vastly better than hanging CI.
+        Task<T> resolution = Task.Run(() => resolve(_provider));
+
+        Task first = await Task.WhenAny(resolution, Task.Delay(ResolveBudget));
+
+        Assert.True(
+            first == resolution,
+            $"Resolving {label} did not complete within {ResolveBudget.TotalSeconds:0}s — " +
+            "the DI singleton cycle deadlock (scadaproj#1) has regressed.");
+
+        return await resolution;
+    }
+
+    public async Task DisposeAsync()
+    {
+        await _provider.DisposeAsync();
+        await _system.Terminate();
+
+        Microsoft.Data.Sqlite.SqliteConnection.ClearAllPools();
+        foreach (string path in new[] { _dbPath, _dbPath + "-wal", _dbPath + "-shm" })
+        {
+            if (File.Exists(path))
+            {
+                File.Delete(path);
+            }
+        }
+    }
+}

components/secrets/GAPS.md

@@ -105,28 +105,42 @@ The KEK control fired spontaneously first: a re-run against a hub still holding
 run (different KEK) threw `SecretDecryptionException` rather than returning garbage — unplanned but
 real evidence of fail-closed.
 
-### Live gate: Akka peer-to-peer (OtOpcUa topology) — ❌ FAILED, blocking defect
+### Live gate: Akka peer-to-peer (OtOpcUa topology) — ✅ PASSES 6/6 (root-caused + fixed in `0.2.2`, 2026-07-18)
 
-**Resolving `ISecretReplicator` hangs indefinitely** in a real clustered process. Reproduced twice
+The `0.2.1` hang is **root-caused and fixed**. It was never Akka at all: the Akka package's DI
-on a healthy 2-node cluster (both members confirmed `Up` before the hang). Isolated by resolving
+wiring had a **circular singleton dependency** the container cannot detect through factory lambdas —
-`ISecretReplicator` *directly* rather than via `ISecretStore`, so it is **not** nested-resolution
+`ISecretStore` (the `ReplicatingSecretStore` decorator) → `ISecretReplicator` →
-contention — the hang is in constructing `AkkaSecretReplicator` → `SecretReplicationActorProvider.ActorRef`
+`SecretReplicationActorProvider` → `ISecretCacheInvalidator` → `DefaultSecretResolver` →
-→ `system.ActorOf(SecretReplicationActor.Props(...))`. Native stacks show `Monitor_Wait`.
+`ISecretStore` again. Resolution recurses around that loop (same-thread `Monitor` re-entry keeps it
+alive) until MS.DI's `StackGuard` moves the recursion onto a fresh thread-pool thread to avoid a
+stack overflow — and that thread then blocks forever on a singleton call-site lock the first thread
+still holds. Managed stacks from a `dotnet-dump` of the hung process show the full cycle repeating
+and both threads parked, which is the `Monitor_Wait` the native samples saw. Both earlier candidate
+causes (`DistributedPubSub.Get` vs the `Lazy<IActorRef>` lock; missing `Akka.Cluster.Tools` HOCON)
+are **disproven** — the actor's constructor was never even reached, and the deadlock reproduces on a
+single-node rig with no clustering in play.
 
-**Impact if enabled:** OtOpcUa would hang at startup, since the wiring resolves `ISecretStore` from a
+**Fix (`0.2.2`):** the one cycle-closing edge is deferred. `SecretReplicationActorProvider` now
-startup hook. It is currently harmless only because `Secrets:Replication:Enabled` defaults false.
+receives a `DeferredSecretCacheInvalidator` that resolves the real invalidator on **first
+eviction** — which can only happen when a replicated row is applied, strictly after the graph has
+finished resolving. The SQL-Server package never had the cycle (its replicator chain never touches
+the invalidator), which is exactly why the hub gate passed while Akka hung.
 
-**Not explained by the library's own suite:** `TwoNodeClusterReplicationTests` creates the same actor
+**Verified:** live convergence gate re-run — **6/6 checks** on a real 2-node cluster (write→peer,
-on a real 2-node cluster and passes (33 tests green). The difference is creation through DI inside a
+delete→tombstone, tombstoned secret no longer resolves on the peer — the check that proves the
-real host process. Root cause NOT yet identified — candidates: `DistributedPubSub.Get(...)` in
+deferred invalidator actually evicts — reverse direction, wrong-KEK fail-closed). Full Akka test
-`PreStart` interacting with the `Lazy<IActorRef>` (`ExecutionAndPublication`) lock, or missing
+project 38/38 green.
-`Akka.Cluster.Tools` reference config in the composed HOCON.
 
-- ⬜ **Do NOT enable `Secrets:Replication:Enabled` in OtOpcUa.** The Akka topology is not adoptable
+- ✅ **Regression test now exists at the exact blind spot:** `HostedProcessResolutionTests` builds
-  until this deadlock is root-caused and fixed, with a regression test that creates the actor
+  the graph the way a host does (container-registered `ActorSystem`, hosted services started, then
-  through DI in a hosted process rather than directly from a test.
+  resolves `ISecretStore`/`ISecretReplicator`/`ISecretResolver` under a 20 s watchdog). Verified to
-  **Tracked:** [`scadaproj#1`](https://gitea.dohertylan.com/dohertj2/scadaproj/issues/1) (the defect,
+  discriminate: it deadlocks/fails on `0.2.1` and passes on `0.2.2`. `DeferredSecretCacheInvalidatorTests`
-  where the library code lives) and [`lmxopcua#482`](https://gitea.dohertylan.com/dohertj2/lmxopcua/issues/482)
+  pins the wrapper's contract (no eager resolve; evictions forward; lookup runs once). This was the
+  **fourth** defect in this library visible only when the DI graph is built inside a real host.
+- ⬜ OtOpcUa may now adopt the Akka topology: bump to `0.2.2` (once published), re-run its gate,
+  then consider enabling `Secrets:Replication:Enabled`.
+  **Tracked:** [`scadaproj#1`](https://gitea.dohertylan.com/dohertj2/scadaproj/issues/1) (the defect —
+  fixed) and [`lmxopcua#482`](https://gitea.dohertylan.com/dohertj2/lmxopcua/issues/482)
   (the consumer-side tracker: bump the package, re-run the gate, then consider enabling).
 - ✅ ScadaBridge's hub topology **is** live-validated and safe to enable (config + a shared KEK).