fix(historian-gateway): wire dormant GatewayTagProvisioner + provisioning observability/docs

PR #423 shipped GatewayTagProvisioner + unit tests but never registered it in DI nor passed it into the AddressSpaceApplier, so deploying historized tags used the no-op NullHistorianProvisioning and never called the gateway's EnsureTags (confirmed live on wonder-app-vd03: zero EnsureTags calls on a historized deploy). Addresses HISTORIAN-GATEWAY-INTEGRATION-ISSUES.md. Issue 1 (wire provisioner): - Runtime: AddHistorianProvisioning extension (gated on ServerHistorian:Enabled, mirrors AddServerHistorian) + NullHistorianProvisioning TryAdd default in AddOtOpcUaRuntime; WithOtOpcUaRuntimeActors resolves IHistorianProvisioning and passes it into the applier. - Gateway driver: GatewayHistorian.CreateProvisioner factory (mirrors CreateDataSource). - Host: Program.cs calls AddHistorianProvisioning after AddServerHistorian. - Tests: AddHistorianProvisioningTests (config-gated registration + the register->resolve->applier->EnsureTags chain). Issue 2 (observability): AddressSpaceApplier logs the provisioning tally on every successful dispatch (was gated behind Failed/Skipped > 0), including dispatched=N so a dispatched=N/requested=0 line flags the dormant no-op. +2 tests. Issue 3 (30s HistoryRead on unprovisioned tags): root coupling fixed by Issue 1; documented the CallTimeout knob + coupling. Default left at 30s pending the multi-data-point investigation the issue requests (lowering risks truncating legitimate large reads). Issue 4 (docs): docs/Historian.md gains a "Tag auto-provisioning (EnsureTags)" section and CLAUDE.md a wiring/gating note (both stress ServerHistorian:Enabled). Sibling scadaproj/CLAUDE.md carries no false claim -> unchanged. Pre-existing Serilog observation: anchor CWD to AppContext.BaseDirectory before AddZbSerilog so the relative file sink stops landing in C:\Windows\System32 under the Windows-service CWD. Builds 0-error; Runtime.Tests 355, OpcUaServer.Tests 329, Gateway.Tests 99 (+4 live-skipped) all green.
2026-06-27 23:24:29 -04:00
parent 245316d80d
commit 257214f775
8 changed files with 416 additions and 7 deletions
@@ -1,3 +1,4 @@
+using Microsoft.Extensions.Logging;
 using Microsoft.Extensions.Logging.Abstractions;
 using Shouldly;
 using Xunit;
@@ -143,6 +144,77 @@ public sealed class AddressSpaceApplierProvisioningTests
        prov.Seen[0].TagName.ShouldBe("Pump1.Good");
    }

+    /// <summary>Capturing <see cref="ILogger{T}"/> that records every log line and signals a
+    /// <see cref="TaskCompletionSource{TResult}"/> the first time a "historian provisioning completed" tally is
+    /// emitted, so the fire-and-forget continuation's log can be awaited deterministically.</summary>
+    private sealed class CapturingLogger : ILogger<AddressSpaceApplier>
+    {
+        private readonly TaskCompletionSource<string> _provisioningLogged =
+            new(TaskCreationOptions.RunContinuationsAsynchronously);
+
+        /// <summary>Completes with the rendered message of the first provisioning-completed tally logged.</summary>
+        public Task<string> ProvisioningLogged => _provisioningLogged.Task;
+
+        public IDisposable BeginScope<TState>(TState state) where TState : notnull => NullScope.Instance;
+
+        public bool IsEnabled(LogLevel logLevel) => true;
+
+        public void Log<TState>(
+            LogLevel logLevel, EventId eventId, TState state, Exception? exception,
+            Func<TState, Exception?, string> formatter)
+        {
+            var message = formatter(state, exception);
+            if (logLevel == LogLevel.Information &&
+                message.Contains("historian provisioning completed", StringComparison.Ordinal))
+            {
+                _provisioningLogged.TrySetResult(message);
+            }
+        }
+
+        private sealed class NullScope : IDisposable
+        {
+            public static readonly NullScope Instance = new();
+            public void Dispose() { }
+        }
+    }
+
+    /// <summary>Issue 2 (observability): a fully-successful provisioning (Ensured>0, Failed=0, Skipped=0) — the
+    /// case that previously logged NOTHING — now emits an Information tally, so a successful provisioning is
+    /// observable rather than silent.</summary>
+    [Fact]
+    public async Task Apply_logs_an_information_tally_on_a_fully_successful_provisioning()
+    {
+        var logger = new CapturingLogger();
+        var applier = new AddressSpaceApplier(
+            NullOpcUaAddressSpaceSink.Instance, logger, new CapturingProvisioner());
+
+        applier.Apply(PlanWithAddedTags(
+            HistorizedTag(displayName: "Temp", historianName: "Pump1.Temp", dataType: "Float32")));
+
+        var message = await logger.ProvisioningLogged.WaitAsync(TimeSpan.FromSeconds(5), TestContext.Current.CancellationToken);
+        message.ShouldContain("dispatched=1");
+        message.ShouldContain("ensured=1");
+        message.ShouldContain("failed=0");
+    }
+
+    /// <summary>Issue 2 (observability): the no-op <see cref="NullHistorianProvisioning"/> path is now
+    /// DETECTABLE — it reports Requested=0 regardless of input, so a tally showing dispatched=1 but requested=0
+    /// unmistakably flags "provisioning is not wired", the invisibility that let the dormant-provisioner bug
+    /// ship unnoticed.</summary>
+    [Fact]
+    public async Task Apply_logs_a_detectable_tally_for_the_noop_provisioning_path()
+    {
+        var logger = new CapturingLogger();
+        var applier = new AddressSpaceApplier(NullOpcUaAddressSpaceSink.Instance, logger);
+
+        applier.Apply(PlanWithAddedTags(
+            HistorizedTag(displayName: "Temp", historianName: "Pump1.Temp", dataType: "Float32")));
+
+        var message = await logger.ProvisioningLogged.WaitAsync(TimeSpan.FromSeconds(5), TestContext.Current.CancellationToken);
+        message.ShouldContain("dispatched=1");  // we DID hand one request to EnsureTagsAsync
+        message.ShouldContain("requested=0");   // ...but the no-op acknowledges nothing ⇒ dormant
+    }
+
    /// <summary>Capturing <see cref="IHistorizedTagSubscriptionSink"/> double. Records the add/remove
    /// ref deltas the applier feeds it. A <see cref="Throw"/> flag simulates a faulting feed.</summary>
    private sealed class CapturingSubscriptionSink : IHistorizedTagSubscriptionSink