feat(mqtt): wire sparkplug.birthObservationWindowSeconds into the browse surface (R06:M-4)

The authored window was persisted and consumed by nothing. It now (clamped 1-120 s)
extends the Sparkplug OpenBudget, bounds a passive UntilStable-style settle on open
(return after a 1 s quiet spell in NBIRTH/DBIRTH traffic), and bounds how long an
operator rebirth request waits for the births it asked for before returning, so the
re-rendered tree carries them. A caller deadline during the wait still reports the
publish.

Refs #744
Claude-Session: https://claude.ai/code/session_01Ub9hGmYLQvn9XETzw7CMsT

src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Mqtt.Browser/MqttBrowseSession.cs

@@ -149,6 +149,9 @@ internal sealed class MqttBrowseSession : IRebirthCapableBrowseSession
     /// </summary>
     private static readonly UTF8Encoding Utf8Strict = new(encoderShouldEmitUTF8Identifier: false, throwOnInvalidBytes: true);
 
+    /// <summary>The quiet spell that ends a rebirth request's wait once its births have started arriving.</summary>
+    private static readonly TimeSpan RebirthQuietInterval = TimeSpan.FromMilliseconds(500);
+
     /// <summary>Bound on the courtesy DISCONNECT issued at dispose — teardown never hangs on a dead broker.</summary>
     private static readonly TimeSpan DisconnectTimeout = TimeSpan.FromSeconds(5);
 
@@ -174,6 +177,7 @@ internal sealed class MqttBrowseSession : IRebirthCapableBrowseSession
     private readonly ConcurrentQueue<string> _publishedTopics = new();
 
     private int _disposed;
+    private long _birthCount;
     private long _lastUsedTicksUtc = DateTime.UtcNow.Ticks;
     private int _nodeCount;
     private int _oversized;
@@ -195,9 +199,16 @@ internal sealed class MqttBrowseSession : IRebirthCapableBrowseSession
     /// <param name="client">The connected MQTT client; disconnected and disposed by <see cref="DisposeAsync"/>.</param>
     /// <param name="logger">Optional logger; never receives credentials or payload bodies.</param>
     /// <param name="nodeCap">Cap on recorded nodes; defaults to <see cref="DefaultNodeCap"/>.</param>
-    internal MqttBrowseSession(MqttMode mode, IMqttClient? client, ILogger? logger, int nodeCap = DefaultNodeCap)
+    /// <param name="birthWindow">
+    ///     The Sparkplug birth-observation window: how long <see cref="RequestRebirthAsync"/> waits for the
+    ///     births it asked for. <see cref="TimeSpan.Zero"/> (the test default) returns as soon as the NCMDs
+    ///     are published.
+    /// </param>
+    internal MqttBrowseSession(
+        MqttMode mode, IMqttClient? client, ILogger? logger, int nodeCap = DefaultNodeCap, TimeSpan birthWindow = default)
     {
         Mode = mode;
+        BirthWindow = birthWindow;
         _client = client;
         _logger = logger;
         _nodeCap = nodeCap;
@@ -211,6 +222,56 @@ internal sealed class MqttBrowseSession : IRebirthCapableBrowseSession
     /// </summary>
     internal int PublishCountForTest => Volatile.Read(ref _publishCount);
 
+    /// <summary>The Sparkplug birth-observation window this session was opened with (R06:M-4).</summary>
+    internal TimeSpan BirthWindow { get; }
+
+    /// <summary>How many NBIRTH/DBIRTH messages this session has observed — the settle loop's signal.</summary>
+    internal long BirthCount => Interlocked.Read(ref _birthCount);
+
+    /// <summary>
+    ///     Waits until birth traffic has gone quiet for one <paramref name="quiet"/> interval, bounded by
+    ///     <paramref name="window"/> — the <c>UntilStable</c> cadence of the birth-observation window.
+    /// </summary>
+    /// <param name="birthCount">Reads the running birth count.</param>
+    /// <param name="baseline">The count before the wait began.</param>
+    /// <param name="awaitFirstBirth">
+    ///     When true, quiet only counts once at least one birth has arrived past <paramref name="baseline"/>
+    ///     — the shape a rebirth request needs, since its answer takes a broker round-trip to arrive.
+    /// </param>
+    /// <param name="quiet">The quiet spell that ends the wait.</param>
+    /// <param name="window">The hard ceiling; non-positive returns at once.</param>
+    /// <param name="cancellationToken">Cancels the wait.</param>
+    /// <returns>A task that completes when the births have settled or the window has elapsed.</returns>
+    internal static async Task SettleBirthsAsync(
+        Func<long> birthCount,
+        long baseline,
+        bool awaitFirstBirth,
+        TimeSpan quiet,
+        TimeSpan window,
+        CancellationToken cancellationToken)
+    {
+        if (window <= TimeSpan.Zero) return;
+
+        var clock = System.Diagnostics.Stopwatch.StartNew();
+        var last = baseline;
+        var sawBirth = !awaitFirstBirth;
+        while (clock.Elapsed < window)
+        {
+            var step = window - clock.Elapsed;
+            await Task.Delay(step < quiet ? step : quiet, cancellationToken).ConfigureAwait(false);
+
+            var now = birthCount();
+            if (now != last)
+            {
+                last = now;
+                sawBirth = true;
+                continue;
+            }
+
+            if (sawBirth) return;
+        }
+    }
+
     /// <summary>The topics this session published, in order — the discriminating view of the above.</summary>
     internal IReadOnlyList<string> PublishedTopicsForTest => [.. _publishedTopics];
 
@@ -557,6 +618,8 @@ internal sealed class MqttBrowseSession : IRebirthCapableBrowseSession
         if (!SparkplugTopic.TryParse(topic, out var parsed)) return;
         if (parsed.Type is not (SparkplugMessageType.NBIRTH or SparkplugMessageType.DBIRTH)) return;
 
+        Interlocked.Increment(ref _birthCount);
+
         // The bound has to be on the whole message: unlike a plain payload, a birth must be parsed
         // entire to yield its metric list, and the parse runs on the shared dispatcher thread.
         if (payload.Length > MaxBirthPayloadBytes)
@@ -898,6 +961,7 @@ internal sealed class MqttBrowseSession : IRebirthCapableBrowseSession
         ArgumentException.ThrowIfNullOrWhiteSpace(scope);
 
         var targets = ResolveRebirthTargets(scope);
+        var baseline = BirthCount;
 
         foreach (var (groupId, edgeNodeId) in targets)
         {
@@ -908,6 +972,20 @@ internal sealed class MqttBrowseSession : IRebirthCapableBrowseSession
                 .ConfigureAwait(false);
         }
 
+        // The birth-observation window (R06:M-4): wait — bounded — for the births just asked for to arrive
+        // and settle, so the tree the picker re-renders after this call already carries them. A courtesy,
+        // never a failure: the NCMDs are out, so a caller deadline here still reports the publish.
+        try
+        {
+            await SettleBirthsAsync(
+                    () => BirthCount, baseline, awaitFirstBirth: true, RebirthQuietInterval, BirthWindow, cancellationToken)
+                .ConfigureAwait(false);
+        }
+        catch (OperationCanceledException)
+        {
+            // Published; the caller simply stopped waiting for the answer.
+        }
+
         Touch();
         return targets.Count;
     }

src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Mqtt.Browser/MqttDriverBrowser.cs

@@ -39,6 +39,15 @@ public sealed class MqttDriverBrowser : IDriverBrowser
     /// <summary>Ceiling on the open budget — the picker must never hang on an unreachable broker.</summary>
     internal const int MaxOpenBudgetSeconds = 30;
 
+    /// <summary>Ceiling on the Sparkplug birth-observation window — an authored hour must not park a picker.</summary>
+    internal const int MaxBirthWindowSeconds = 120;
+
+    /// <summary>
+    ///     How long the open waits for a quiet spell in birth traffic before handing the session back. An
+    ///     idle plant (births are never retained) costs exactly this, once.
+    /// </summary>
+    internal static readonly TimeSpan BirthQuietInterval = TimeSpan.FromSeconds(1);
+
     /// <summary>Marks the transient browse identity in the broker's client-id/session logs.</summary>
     internal const string BrowseClientIdPrefix = "-browse-";
 
@@ -77,7 +86,8 @@ public sealed class MqttDriverBrowser : IDriverBrowser
         openCts.CancelAfter(OpenBudget(opts));
 
         var client = new MqttClientFactory().CreateMqttClient();
-        var session = new MqttBrowseSession(opts.Mode, client, _logger);
+        var birthWindow = opts.Mode == MqttMode.SparkplugB ? BirthWindow(opts) : TimeSpan.Zero;
+        var session = new MqttBrowseSession(opts.Mode, client, _logger, birthWindow: birthWindow);
         try
         {
             // Runs on MQTTnet's dispatcher: record and return, nothing else.
@@ -100,6 +110,29 @@ public sealed class MqttDriverBrowser : IDriverBrowser
                 .Build();
             await client.SubscribeAsync(subscribeOptions, openCts.Token).ConfigureAwait(false);
 
+            if (opts.Mode == MqttMode.SparkplugB)
+            {
+                // The birth-observation window (R06:M-4): births already in flight — an edge node mid-rebirth,
+                // a primary-host flap — are collected until the traffic goes quiet, bounded by the window, so
+                // the first RootAsync is not a snapshot taken in the middle of a burst. Passive: nothing is
+                // published to provoke a birth. An idle plant costs one quiet interval.
+                try
+                {
+                    await MqttBrowseSession.SettleBirthsAsync(
+                            () => session.BirthCount,
+                            baseline: session.BirthCount,
+                            awaitFirstBirth: false,
+                            BirthQuietInterval,
+                            birthWindow,
+                            openCts.Token)
+                        .ConfigureAwait(false);
+                }
+                catch (OperationCanceledException) when (!cancellationToken.IsCancellationRequested)
+                {
+                    // The open budget ran out mid-settle: what has been observed is still a usable session.
+                }
+            }
+
             _logger.LogInformation(
                 "AdminUI MQTT browse session opened against {Host}:{Port} in {Mode} mode observing "
                 + "'{Filter}' (read-only).",
@@ -179,12 +212,30 @@ public sealed class MqttDriverBrowser : IDriverBrowser
         options with { CleanSession = true };
 
     /// <summary>
-    ///     Whole-open bound (connect + subscribe), clamped to
-    ///     <see cref="MinOpenBudgetSeconds"/>–<see cref="MaxOpenBudgetSeconds"/> around the config's
-    ///     own connect deadline.
+    ///     Whole-open bound: connect + subscribe, clamped to
+    ///     <see cref="MinOpenBudgetSeconds"/>–<see cref="MaxOpenBudgetSeconds"/> around the config's own
+    ///     connect deadline — plus, in Sparkplug mode, the <see cref="BirthWindow"/> the open may spend
+    ///     collecting births.
     /// </summary>
     /// <param name="options">The browse configuration.</param>
-    /// <returns>The clamped open budget.</returns>
-    internal static TimeSpan OpenBudget(MqttDriverOptions options) =>
-        TimeSpan.FromSeconds(Math.Clamp(options.ConnectTimeoutSeconds, MinOpenBudgetSeconds, MaxOpenBudgetSeconds));
+    /// <returns>The open budget.</returns>
+    internal static TimeSpan OpenBudget(MqttDriverOptions options)
+    {
+        var connect = TimeSpan.FromSeconds(
+            Math.Clamp(options.ConnectTimeoutSeconds, MinOpenBudgetSeconds, MaxOpenBudgetSeconds));
+        return options.Mode == MqttMode.SparkplugB ? connect + BirthWindow(options) : connect;
+    }
+
+    /// <summary>
+    ///     The authored <c>sparkplug.birthObservationWindowSeconds</c>, clamped to 1–<see cref="MaxBirthWindowSeconds"/>
+    ///     s: how long the browse surface collects NBIRTH/DBIRTH traffic before calling the observed metric set
+    ///     stable (on open, and after an operator rebirth request).
+    /// </summary>
+    /// <param name="options">The browse configuration.</param>
+    /// <returns>The clamped window.</returns>
+    internal static TimeSpan BirthWindow(MqttDriverOptions options) =>
+        TimeSpan.FromSeconds(Math.Clamp(
+            options.Sparkplug?.BirthObservationWindowSeconds ?? new MqttSparkplugOptions().BirthObservationWindowSeconds,
+            1,
+            MaxBirthWindowSeconds));
 }