feat(historian-gateway): EnsureTags provisioning hook in AddressSpaceApplier (non-blocking)

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

src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/AddressSpaceApplier.cs

@@ -1,5 +1,6 @@
 using Microsoft.Extensions.Logging;
 using ZB.MOM.WW.OtOpcUa.Commons.OpcUa;
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
 
 namespace ZB.MOM.WW.OtOpcUa.OpcUaServer;
 
@@ -27,16 +28,29 @@ public sealed class AddressSpaceApplier
 {
     private readonly IOpcUaAddressSpaceSink _sink;
     private readonly ILogger<AddressSpaceApplier> _logger;
+    private readonly IHistorianProvisioning _provisioning;
 
     /// <summary>Initializes a new instance of the AddressSpaceApplier class.</summary>
     /// <param name="sink">The OPC UA address space sink to apply changes to.</param>
     /// <param name="logger">The logger instance.</param>
-    public AddressSpaceApplier(IOpcUaAddressSpaceSink sink, ILogger<AddressSpaceApplier> logger)
+    /// <param name="provisioning">
+    ///     Optional historian tag provisioner — when an address space is (re)built, historized added
+    ///     tags are auto-ensured in the historian via <see cref="IHistorianProvisioning.EnsureTagsAsync"/>.
+    ///     Defaults (a <c>null</c> argument) to the no-op <see cref="NullHistorianProvisioning"/>, so every
+    ///     existing two-argument call site compiles and behaves unchanged. The provisioning round-trip is
+    ///     dispatched fire-and-forget off <see cref="Apply"/> (which runs on the OPC UA publish actor's
+    ///     pinned thread), so it can never block or break a deploy.
+    /// </param>
+    public AddressSpaceApplier(
+        IOpcUaAddressSpaceSink sink,
+        ILogger<AddressSpaceApplier> logger,
+        IHistorianProvisioning? provisioning = null)
     {
         ArgumentNullException.ThrowIfNull(sink);
         ArgumentNullException.ThrowIfNull(logger);
         _sink = sink;
         _logger = logger;
+        _provisioning = provisioning ?? NullHistorianProvisioning.Instance;
     }
 
     /// <summary>
@@ -177,9 +191,88 @@ public sealed class AddressSpaceApplier
             "AddressSpaceApplier: applied plan (added={Added}, removed={Removed}, changed={Changed}, surgicalTags={Surgical}, renamedFolders={Renamed}, rebuild={Rebuild})",
             addedCount, removedCount, changedCount, rebuilt ? 0 : surgicalTagDeltas.Count, rebuilt ? 0 : renamedFolders.Count, rebuilt);
 
+        // After the address-space work has completed, auto-provision the historian for the added
+        // historized tags. This is fully detached (fire-and-forget) and wrapped so it can NEVER block
+        // or break the deploy — Apply has already produced its outcome and returns it regardless.
+        ProvisionHistorizedTags(plan);
+
         return new AddressSpaceApplyOutcome(removedCount, addedCount, changedCount, rebuilt);
     }
 
+    /// <summary>
+    ///     Auto-provision the historian for the added historized equipment tags. Runs on the OPC UA
+    ///     publish actor's pinned thread, so the synchronous portion is kept to building the request
+    ///     list only and the gateway round-trip is dispatched fire-and-forget. The whole hook is wrapped
+    ///     in try/catch — a synchronously-throwing provisioner (or any request-building fault) is
+    ///     swallowed so it cannot break a deploy.
+    /// </summary>
+    /// <param name="plan">The plan whose added historized tags to ensure in the historian.</param>
+    private void ProvisionHistorizedTags(AddressSpacePlan plan)
+    {
+        try
+        {
+            List<HistorianTagProvisionRequest>? requests = null;
+            foreach (var tag in plan.AddedEquipmentTags)
+            {
+                // Only historized value variables are provisioned. Native-alarm tags materialise as
+                // Part 9 condition nodes (never historized value variables) — the materialiser resolves
+                // a historian tagname only for the non-alarm branch, so mirror that and skip them.
+                if (!tag.IsHistorized || tag.Alarm is not null) continue;
+
+                // Parse the driver-agnostic data type from the tag's DataType string. An unparseable
+                // type is skipped (logged at Debug) rather than faulting the hook.
+                if (!Enum.TryParse<DriverDataType>(tag.DataType, ignoreCase: true, out var dataType))
+                {
+                    _logger.LogDebug(
+                        "AddressSpaceApplier: skipping historian provisioning for an added historized tag whose data type '{DataType}' is not a DriverDataType",
+                        tag.DataType);
+                    continue;
+                }
+
+                // Resolve the historian name EXACTLY as MaterialiseEquipmentTags does: a null/blank
+                // override falls back to the driver-side FullName.
+                var historianName = string.IsNullOrWhiteSpace(tag.HistorianTagname) ? tag.FullName : tag.HistorianTagname;
+                (requests ??= new List<HistorianTagProvisionRequest>()).Add(
+                    new HistorianTagProvisionRequest(historianName, dataType, EngineeringUnit: null, Description: tag.Name));
+            }
+
+            if (requests is null) return;
+
+            // Fire-and-forget OFF the apply path. Never await/.Wait()/.Result here — Apply must return
+            // its outcome without blocking on the gateway. The continuation observes the task so a
+            // faulted provisioning never becomes an unobserved exception, and logs the tally.
+            var provisionCount = requests.Count;
+            var dispatch = _provisioning.EnsureTagsAsync(requests, CancellationToken.None);
+            _ = dispatch.ContinueWith(
+                t =>
+                {
+                    if (t.IsFaulted)
+                    {
+                        _logger.LogWarning(t.Exception?.GetBaseException(),
+                            "AddressSpaceApplier: historian provisioning of {Count} tag(s) faulted; deploy unaffected", provisionCount);
+                        return;
+                    }
+
+                    var result = t.Result;
+                    if (result.Failed > 0 || result.Skipped > 0)
+                    {
+                        _logger.LogInformation(
+                            "AddressSpaceApplier: historian provisioning completed (requested={Requested}, ensured={Ensured}, skipped={Skipped}, failed={Failed})",
+                            result.Requested, result.Ensured, result.Skipped, result.Failed);
+                    }
+                },
+                CancellationToken.None,
+                TaskContinuationOptions.None,
+                TaskScheduler.Default);
+        }
+        catch (Exception ex)
+        {
+            // A synchronous fault (e.g. the provisioner throws before returning a task) must not break
+            // the deploy. Apply has already produced its outcome.
+            _logger.LogWarning(ex, "AddressSpaceApplier: historian provisioning hook faulted synchronously; deploy unaffected");
+        }
+    }
+
     private void SafeRebuild()
     {
         try

src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/ZB.MOM.WW.OtOpcUa.OpcUaServer.csproj

@@ -16,6 +16,7 @@
     </ItemGroup>
 
     <ItemGroup>
+        <ProjectReference Include="..\..\Core\ZB.MOM.WW.OtOpcUa.Core.Abstractions\ZB.MOM.WW.OtOpcUa.Core.Abstractions.csproj"/>
         <ProjectReference Include="..\..\Core\ZB.MOM.WW.OtOpcUa.Commons\ZB.MOM.WW.OtOpcUa.Commons.csproj"/>
         <ProjectReference Include="..\..\Core\ZB.MOM.WW.OtOpcUa.Configuration\ZB.MOM.WW.OtOpcUa.Configuration.csproj"/>
     </ItemGroup>