feat(drivers): consume IRediscoverable as an operator re-browse prompt (§8.2, #518)

Nine drivers raise IRediscoverable.OnRediscoveryNeeded when they observe that
a remote's tag set may have changed — a Galaxy redeploy, a TwinCAT
symbol-version bump, an MTConnect agent restart, a Sparkplug rebirth. Nothing
in src/ subscribed, so every raise went into the void. Drivers even wrap the
invoke in try/catch for "subscriber threw"; there has never been a subscriber.

DriverInstanceActor now attaches the event in PreStart and detaches in
PostStop, mirroring AttachAlarmSource/DetachAlarmSource. Attach is per-actor,
not per-connect: the raise has no connection affinity and can land while the
driver is between connects. The detach is load-bearing rather than tidy — the
IDriver instance outlives the actor when the host respawns a child around the
same driver object, so a missing -= accumulates one handler per respawn, each
holding a dead Self.

The signal rides the existing driver-health snapshot to /hosts as a
"re-browse" chip. It is ADVISORY: the served address space is deliberately not
rebuilt, because v3 authors raw tags explicitly through the /raw
browse-commit flow and a runtime graft would materialise nodes no operator
approved and no deployment artifact records.

Two things worth knowing:

- PublishHealthSnapshot dedups on a health fingerprint, and a rediscovery
  raise on an otherwise-healthy driver changes none of the four fields it
  hashed. Without adding the timestamp to that tuple the dedup swallows the
  exact publish carrying the signal. Reverting that one line turns 3 of the 5
  new tests red, which is how it was confirmed rather than assumed.
- The new test stub implements IDriver from scratch instead of deriving from
  the shared StubDriver, whose GetHealth() returns DateTime.UtcNow — its
  fingerprint differs on every call, so the dedup never engages and the dedup
  test would have passed vacuously either way.

The planned discovery-result drift detector was NOT built. Modbus, S7, MQTT,
AbLegacy and Sql all echo authored config from DiscoverAsync rather than
browsing the device, so a discovered-vs-authored diff is permanently empty for
them — it would have been another plausible-looking inert seam, which is the
class this audit exists to remove. IRediscoverable is the trustworthy signal
because the driver asserts it deliberately.

DriverHealthChanged, IDriverHealthPublisher.Publish and HostsDriverRow gain
defaulted optional parameters, so no existing call site changed. telemetry.proto
gains fields 8/9 and both Phase-5 mappers carry them.

Runtime.Tests 512 passed / 31 skipped.

src/Server/ZB.MOM.WW.OtOpcUa.Runtime/Drivers/AkkaDriverHealthPublisher.cs

@@ -30,7 +30,13 @@ public sealed class AkkaDriverHealthPublisher : IDriverHealthPublisher
     }
 
     /// <inheritdoc />
-    public void Publish(string clusterId, string driverInstanceId, DriverHealth health, int errorCount5Min)
+    public void Publish(
+        string clusterId,
+        string driverInstanceId,
+        DriverHealth health,
+        int errorCount5Min,
+        DateTime? rediscoveryNeededUtc = null,
+        string? rediscoveryReason = null)
     {
         var msg = new DriverHealthChanged(
             clusterId,
@@ -39,7 +45,9 @@ public sealed class AkkaDriverHealthPublisher : IDriverHealthPublisher
             health.LastSuccessfulRead,
             health.LastError,
             errorCount5Min,
-            DateTime.UtcNow);
+            DateTime.UtcNow,
+            rediscoveryNeededUtc,
+            rediscoveryReason);
         DistributedPubSub.Get(_system).Mediator.Tell(new Publish(TopicName, msg));
         // Phase 5: fan the same snapshot into the node-local live-telemetry hub (no-op until a gRPC
         // client subscribes). The DPS publish above is unchanged — the hub is a strictly additive tap.

src/Server/ZB.MOM.WW.OtOpcUa.Runtime/Drivers/DriverInstanceActor.cs

@@ -139,6 +139,13 @@ public sealed class DriverInstanceActor : ReceiveActor, IWithTimers
     /// </summary>
     public sealed record TriggerRediscovery;
 
+    /// <summary>Self-sent when the wrapped driver raises <see cref="IRediscoverable.OnRediscoveryNeeded"/> —
+    /// it observed that the remote's tag set may have changed. Marshals the event off the driver's thread
+    /// onto the actor thread. Handled in EVERY behaviour, including Stubbed and Reconnecting: the raise has no
+    /// connection affinity (a Galaxy redeploy or a TwinCAT symbol-version bump can land while the driver is
+    /// between connects), and dropping it in one state would lose the signal silently.</summary>
+    private sealed record RediscoveryRaised(RediscoveryEventArgs Args);
+
     /// <summary>Internal self-tick driving bounded post-connect re-discovery (FixedTree populates ~0–2s after connect).
     /// <paramref name="PreviousSignature"/> is the ordered-distinct full-reference signature of the prior pass's
     /// captured set (empty string on the first tick); re-discovery stops once a non-empty set repeats it.</summary>
@@ -203,6 +210,16 @@ public sealed class DriverInstanceActor : ReceiveActor, IWithTimers
     private ISubscriptionHandle? _subscriptionHandle;
     private EventHandler<DataChangeEventArgs>? _dataChangeHandler;
     private EventHandler<AlarmEventArgs>? _alarmEventHandler;
+    private EventHandler<RediscoveryEventArgs>? _rediscoveryHandler;
+
+    /// <summary>When the driver last raised <see cref="IRediscoverable.OnRediscoveryNeeded"/>, and the reason
+    /// it gave. Null until the first raise. Carried on every subsequent health snapshot so the AdminUI can
+    /// prompt an operator to re-browse the device.
+    /// <para>Deliberately <b>sticky</b> — it is not cleared on reconnect or on a later clean pass. The remote's
+    /// tag set stayed changed; only an operator re-browsing and committing resolves it, and this actor cannot
+    /// observe that happening. A redeploy respawns the child, which clears it naturally.</para></summary>
+    private DateTime? _rediscoveryNeededUtc;
+    private string? _rediscoveryReason;
 
     /// <summary>The references the host wants kept subscribed (set by <see cref="SetDesiredSubscriptions"/>).
     /// Re-applied on every entry into <c>Connected</c> so values resume after a reconnect or redeploy.</summary>
@@ -344,6 +361,9 @@ public sealed class DriverInstanceActor : ReceiveActor, IWithTimers
         // Warm up the snapshot store immediately so AdminUI sees current state as soon as the
         // actor starts, before any state transition fires. Also start the periodic heartbeat so
         // long-lived Healthy drivers keep their snapshot fresh for newly-joined SignalR clients.
+        // Attach the rediscovery signal before the first publish. Not per-connect: an IRediscoverable raise
+        // has no connection affinity, and a driver can observe a remote change while disconnected.
+        AttachRediscoverySource();
         PublishHealthSnapshot();
         Timers.StartPeriodicTimer("health-poll", HealthPollTick.Instance, _healthPollInterval);
     }
@@ -365,6 +385,7 @@ public sealed class DriverInstanceActor : ReceiveActor, IWithTimers
         Receive<RediscoverTick>(_ => { });
         // A TriggerRediscovery is meaningless to a stubbed (never-Connected) driver — silently ignore it.
         Receive<TriggerRediscovery>(_ => { });
+        Receive<RediscoveryRaised>(HandleRediscoveryRaised);
         Receive<HealthPollTick>(_ => PublishHealthSnapshot());
     }
 
@@ -424,6 +445,7 @@ public sealed class DriverInstanceActor : ReceiveActor, IWithTimers
         // A TriggerRediscovery arriving while not Connected is a deliberate no-op — the (re)connect path
         // re-runs discovery anyway. Swallow it so it stays a clean silent no-op (no Unhandled event).
         Receive<TriggerRediscovery>(_ => { });
+        Receive<RediscoveryRaised>(HandleRediscoveryRaised);
         Receive<HealthPollTick>(_ => PublishHealthSnapshot());
     }
 
@@ -499,6 +521,7 @@ public sealed class DriverInstanceActor : ReceiveActor, IWithTimers
         // to Self (HandleSubscribeAsync already logged the underlying cause). Swallow it so it doesn't dead-letter.
         Receive<SubscriptionFailed>(msg =>
             _log.Debug("DriverInstance {Id}: resubscribe reported failure: {Reason}", _driverInstanceId, msg.Reason));
+        Receive<RediscoveryRaised>(HandleRediscoveryRaised);
         Receive<HealthPollTick>(_ =>
         {
             PublishHealthSnapshot();
@@ -608,6 +631,7 @@ public sealed class DriverInstanceActor : ReceiveActor, IWithTimers
         // A TriggerRediscovery arriving while not Connected is a deliberate no-op — the (re)connect path
         // re-runs discovery anyway. Swallow it so it stays a clean silent no-op (no Unhandled event).
         Receive<TriggerRediscovery>(_ => { });
+        Receive<RediscoveryRaised>(HandleRediscoveryRaised);
         Receive<HealthPollTick>(_ => PublishHealthSnapshot());
         Timers.StartPeriodicTimer("retry-connect", RetryConnect.Instance, _reconnectInterval);
     }
@@ -853,6 +877,44 @@ public sealed class DriverInstanceActor : ReceiveActor, IWithTimers
         src.OnAlarmEvent += _alarmEventHandler;
     }
 
+    /// <summary>Subscribe the driver's <see cref="IRediscoverable.OnRediscoveryNeeded"/> (if it is one),
+    /// marshaling each raise to the actor thread. Idempotent; mirrors <see cref="AttachAlarmSource"/>.
+    /// <para>Attached once in <c>PreStart</c> rather than per-connect, because the interesting raises
+    /// (a Galaxy redeploy, a TwinCAT symbol-version bump) can happen while the driver is between
+    /// connects, and the event carries no connection affinity.</para></summary>
+    private void AttachRediscoverySource()
+    {
+        if (_driver is not IRediscoverable src || _rediscoveryHandler is not null) return;
+        var self = Self;
+        _rediscoveryHandler = (_, e) => self.Tell(new RediscoveryRaised(e));
+        src.OnRediscoveryNeeded += _rediscoveryHandler;
+    }
+
+    /// <summary>Symmetric teardown, called from PostStop. Load-bearing: the <see cref="IDriver"/> instance
+    /// can OUTLIVE this actor (the host respawns a child around the same driver object), so a missing
+    /// unsubscribe would accumulate one handler per respawn, each holding a dead <c>Self</c>.</summary>
+    private void DetachRediscoverySource()
+    {
+        if (_driver is IRediscoverable src && _rediscoveryHandler is not null)
+            src.OnRediscoveryNeeded -= _rediscoveryHandler;
+        _rediscoveryHandler = null;
+    }
+
+    /// <summary>Records the driver's rediscovery raise and re-publishes health so the signal reaches the
+    /// AdminUI promptly rather than waiting for the next 30 s heartbeat.
+    /// <para><b>Advisory only.</b> The served address space is deliberately NOT rebuilt: v3 authors raw tags
+    /// explicitly through the <c>/raw</c> browse-commit flow, so a runtime graft would create nodes no
+    /// operator approved and that no deployment artifact records. This prompts a human to re-browse.</para></summary>
+    private void HandleRediscoveryRaised(RediscoveryRaised msg)
+    {
+        _rediscoveryNeededUtc = DateTime.UtcNow;
+        _rediscoveryReason = msg.Args.Reason;
+        _log.Info(
+            "DriverInstance {Id}: driver reports its tag set may have changed ({Reason}) — surfaced for operator re-browse; the served address space is unchanged",
+            _driverInstanceId, msg.Args.Reason);
+        PublishHealthSnapshot();
+    }
+
     /// <summary>Symmetric teardown — called from <see cref="DetachSubscription"/> and PostStop so a stale
     /// handler never pushes to a disconnected actor.</summary>
     private void DetachAlarmSource()
@@ -1081,11 +1143,16 @@ public sealed class DriverInstanceActor : ReceiveActor, IWithTimers
         {
             var health = _driver.GetHealth();
             var errorCount = ErrorCount5Min();
-            var fingerprint = (health.State, health.LastSuccessfulRead, health.LastError, errorCount);
+            // _rediscoveryNeededUtc is PART OF THE FINGERPRINT on purpose. A rediscovery raise on an
+            // otherwise-unchanged Healthy driver leaves (state, lastSuccess, lastError, errorCount)
+            // identical, so without it the dedup below would swallow the very publish that carries the
+            // signal and the operator would never see the prompt.
+            var fingerprint = (health.State, health.LastSuccessfulRead, health.LastError, errorCount, _rediscoveryNeededUtc);
             if (_lastPublishedFingerprint is { } prev && prev.Equals(fingerprint))
                 return;
             _lastPublishedFingerprint = fingerprint;
-            _healthPublisher.Publish(_clusterId, _driverInstanceId, health, errorCount);
+            _healthPublisher.Publish(
+                _clusterId, _driverInstanceId, health, errorCount, _rediscoveryNeededUtc, _rediscoveryReason);
         }
         catch (Exception ex)
         {
@@ -1094,12 +1161,15 @@ public sealed class DriverInstanceActor : ReceiveActor, IWithTimers
     }
 
     /// <summary>Fingerprint of the last <see cref="PublishHealthSnapshot"/> call; null until first publish.</summary>
-    private (DriverState State, DateTime? LastSuccess, string? LastError, int ErrorCount)? _lastPublishedFingerprint;
+    private (DriverState State, DateTime? LastSuccess, string? LastError, int ErrorCount, DateTime? RediscoveryNeededUtc)? _lastPublishedFingerprint;
 
     /// <inheritdoc />
     protected override void PostStop()
     {
         DetachSubscription();
+        // MUST happen: the IDriver instance can outlive this actor (the host respawns a child around the
+        // same driver object), so a missing unsubscribe accumulates a handler per respawn holding a dead Self.
+        DetachRediscoverySource();
         try { _driver.ShutdownAsync(CancellationToken.None).GetAwaiter().GetResult(); }
         catch (Exception ex) { _log.Warning(ex, "DriverInstance {Id}: ShutdownAsync threw on PostStop", _driverInstanceId); }
         OtOpcUaTelemetry.DriverInstanceLifecycle.Add(1,