fix(r2-02): options-generation in the pipeline cache key — stale respawn re-cache unreachable (01/S-7, 03/S13)

src/Core/ZB.MOM.WW.OtOpcUa.Core/Resilience/CapabilityInvoker.cs

@@ -28,6 +28,7 @@ public sealed class CapabilityInvoker : IDriverCapabilityInvoker
     private readonly string _driverType;
     private readonly Func<DriverResilienceOptions> _optionsAccessor;
     private readonly DriverResilienceStatusTracker? _statusTracker;
+    private readonly long _optionsGeneration;
     private DriverResilienceOptions? _noRetryWriteOptions;
 
     /// <summary>
@@ -41,12 +42,18 @@ public sealed class CapabilityInvoker : IDriverCapabilityInvoker
     /// </param>
     /// <param name="driverType">Driver type name for structured-log enrichment (e.g. <c>"Modbus"</c>).</param>
     /// <param name="statusTracker">Optional resilience-status tracker. When wired, every capability call records start/complete so Admin <c>/hosts</c> can surface <see cref="ResilienceStatusSnapshot.CurrentInFlight"/> as the in-flight-call-depth proxy.</param>
+    /// <param name="optionsGeneration">
+    ///     Options epoch for this invoker (01/S-7). Threaded into every pipeline-cache lookup so a lingering
+    ///     old child's late re-cache can never poison a newer invoker's pipeline. Defaults to 0 so existing
+    ///     callers/tests are unaffected.
+    /// </param>
     public CapabilityInvoker(
         DriverResiliencePipelineBuilder builder,
         string driverInstanceId,
         Func<DriverResilienceOptions> optionsAccessor,
         string driverType = "Unknown",
-        DriverResilienceStatusTracker? statusTracker = null)
+        DriverResilienceStatusTracker? statusTracker = null,
+        long optionsGeneration = 0)
     {
         ArgumentNullException.ThrowIfNull(builder);
         ArgumentNullException.ThrowIfNull(optionsAccessor);
@@ -56,6 +63,7 @@ public sealed class CapabilityInvoker : IDriverCapabilityInvoker
         _driverType = driverType;
         _optionsAccessor = optionsAccessor;
         _statusTracker = statusTracker;
+        _optionsGeneration = optionsGeneration;
     }
 
     /// <inheritdoc />
@@ -123,7 +131,7 @@ public sealed class CapabilityInvoker : IDriverCapabilityInvoker
             // safe and removes the per-write allocation the previous once-per-call snapshot incurred. The
             // null-check-assign tolerates a benign first-call race (both threads build an equivalent record).
             var noRetryOptions = _noRetryWriteOptions ??= BuildNoRetryWriteOptions();
-            var pipeline = _builder.GetOrCreate(_driverInstanceId, $"{hostName}::non-idempotent", DriverCapability.Write, noRetryOptions);
+            var pipeline = _builder.GetOrCreate(_driverInstanceId, $"{hostName}::non-idempotent", DriverCapability.Write, noRetryOptions, _optionsGeneration);
             // Record in-flight accounting on the CALLER's host (the "::non-idempotent" suffix is a
             // pipeline-cache key, not an operator-facing host) so Admin /hosts sees write depth too.
             _statusTracker?.RecordCallStart(_driverInstanceId, hostName);
@@ -156,5 +164,5 @@ public sealed class CapabilityInvoker : IDriverCapabilityInvoker
     }
 
     private ResiliencePipeline ResolvePipeline(DriverCapability capability, string hostName) =>
-        _builder.GetOrCreate(_driverInstanceId, hostName, capability, _optionsAccessor());
+        _builder.GetOrCreate(_driverInstanceId, hostName, capability, _optionsAccessor(), _optionsGeneration);
 }

src/Core/ZB.MOM.WW.OtOpcUa.Core/Resilience/DriverResiliencePipelineBuilder.cs

@@ -69,23 +69,35 @@ public sealed class DriverResiliencePipelineBuilder
     /// </param>
     /// <param name="capability">Which capability surface is being called.</param>
     /// <param name="options">Per-driver-instance options (tier + per-capability overrides).</param>
+    /// <param name="optionsGeneration">
+    ///     Monotonic options epoch stamped by <see cref="DriverCapabilityInvokerFactory"/> per invoker
+    ///     (01/S-7). Part of the cache key so a lingering old child's post-invalidate re-cache lands under
+    ///     its OWN (old) generation — a key the new invoker's generation never reads. Defaults to 0 so
+    ///     every existing caller/test compiles unchanged.
+    /// </param>
     /// <returns>The cached or newly built resilience pipeline for the key.</returns>
     public ResiliencePipeline GetOrCreate(
         string driverInstanceId,
         string hostName,
         DriverCapability capability,
-        DriverResilienceOptions options)
+        DriverResilienceOptions options,
+        long optionsGeneration = 0)
     {
         ArgumentNullException.ThrowIfNull(options);
         ArgumentException.ThrowIfNullOrWhiteSpace(hostName);
 
-        var key = new PipelineKey(driverInstanceId, hostName, capability);
+        var key = new PipelineKey(driverInstanceId, hostName, capability, optionsGeneration);
         return _pipelines.GetOrAdd(key, static (k, state) => Build(
                 k.DriverInstanceId, k.HostName, state.capability, state.options, state.timeProvider, state.tracker, state.logger),
             (capability, options, timeProvider: _timeProvider, tracker: _statusTracker, logger: _logger));
     }
 
-    /// <summary>Drop cached pipelines for one driver instance (e.g. on ResilienceConfig change). Test + Admin-reload use.</summary>
+    /// <summary>
+    ///     Drop cached pipelines for one driver instance (e.g. on ResilienceConfig change), across ALL
+    ///     option generations. With generation-keyed entries (01/S-7) correctness no longer depends on this
+    ///     sweep — a stale-epoch re-cache is already unreachable by the new generation — but it bounds the
+    ///     cache by clearing lingering old-generation entries on the next respawn. Test + Admin-reload use.
+    /// </summary>
     /// <param name="driverInstanceId">The driver instance ID whose pipelines should be invalidated.</param>
     /// <returns>The number of pipelines removed.</returns>
     public int Invalidate(string driverInstanceId)
@@ -188,5 +200,5 @@ public sealed class DriverResiliencePipelineBuilder
         return builder.Build();
     }
 
-    private readonly record struct PipelineKey(string DriverInstanceId, string HostName, DriverCapability Capability);
+    private readonly record struct PipelineKey(string DriverInstanceId, string HostName, DriverCapability Capability, long Generation);
 }