feat(opcua): EnsureVariable array params (ValueRank=OneDimension + ArrayDimensions)

src/Core/ZB.MOM.WW.OtOpcUa.Commons/OpcUa/DeferredAddressSpaceSink.cs

@@ -62,8 +62,10 @@ public sealed class DeferredAddressSpaceSink : IOpcUaAddressSpaceSink
     /// <param name="writable">When true the node is created read/write; otherwise read-only.</param>
     /// <param name="historianTagname">null ⇒ not historized; non-null ⇒ create Historizing with the
     /// HistoryRead access bit and register the historian tagname.</param>
-    public void EnsureVariable(string variableNodeId, string? parentFolderNodeId, string displayName, string dataType, bool writable, string? historianTagname = null)
-        => _inner.EnsureVariable(variableNodeId, parentFolderNodeId, displayName, dataType, writable, historianTagname);
+    /// <param name="isArray">When true the node is created as a 1-D array; when false (default) scalar.</param>
+    /// <param name="arrayLength">The declared length of the 1-D array when <paramref name="isArray"/> is true.</param>
+    public void EnsureVariable(string variableNodeId, string? parentFolderNodeId, string displayName, string dataType, bool writable, string? historianTagname = null, bool isArray = false, uint? arrayLength = null)
+        => _inner.EnsureVariable(variableNodeId, parentFolderNodeId, displayName, dataType, writable, historianTagname, isArray, arrayLength);
 
     /// <summary>Rebuilds the address space through the inner sink.</summary>
     public void RebuildAddressSpace() => _inner.RebuildAddressSpace();

src/Core/ZB.MOM.WW.OtOpcUa.Commons/OpcUa/IOpcUaAddressSpaceSink.cs

@@ -71,7 +71,13 @@ public interface IOpcUaAddressSpaceSink
     /// <param name="historianTagname">null ⇒ the variable is not historized; non-null ⇒ create it
     /// Historizing with the HistoryRead access bit and register the (already default-resolved)
     /// historian tagname.</param>
-    void EnsureVariable(string variableNodeId, string? parentFolderNodeId, string displayName, string dataType, bool writable, string? historianTagname = null);
+    /// <param name="isArray">When true the node is created as a 1-D array (<c>ValueRank=OneDimension</c>
+    /// with <c>ArrayDimensions=[arrayLength]</c>); when false (default) it stays scalar
+    /// (<c>ValueRank=Scalar</c>). Array elements share the scalar's base <paramref name="dataType"/> —
+    /// rank + dimensions carry the array-ness.</param>
+    /// <param name="arrayLength">The declared length of the 1-D array when <paramref name="isArray"/> is
+    /// true; ignored for scalars. Null ⇒ length 0 (unbounded).</param>
+    void EnsureVariable(string variableNodeId, string? parentFolderNodeId, string displayName, string dataType, bool writable, string? historianTagname = null, bool isArray = false, uint? arrayLength = null);
 
     /// <summary>
     ///     Tear down + repopulate the address space. Called by <c>OpcUaPublishActor</c> after a
@@ -104,7 +110,7 @@ public sealed class NullOpcUaAddressSpaceSink : IOpcUaAddressSpaceSink
     public void EnsureFolder(string folderNodeId, string? parentNodeId, string displayName) { }
 
     /// <inheritdoc />
-    public void EnsureVariable(string variableNodeId, string? parentFolderNodeId, string displayName, string dataType, bool writable, string? historianTagname = null) { }
+    public void EnsureVariable(string variableNodeId, string? parentFolderNodeId, string displayName, string dataType, bool writable, string? historianTagname = null, bool isArray = false, uint? arrayLength = null) { }
 
     /// <inheritdoc />
     public void RebuildAddressSpace() { }

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

@@ -1296,7 +1296,13 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2
     /// <c>HistoryRead</c> access bit OR-ed into both <c>AccessLevel</c> and <c>UserAccessLevel</c>, and the
     /// (already default-resolved) tagname is registered in the NodeId→tagname map the HistoryRead override
     /// resolves against.</param>
-    public void EnsureVariable(string variableNodeId, string? parentFolderNodeId, string displayName, string dataType, bool writable, string? historianTagname = null)
+    /// <param name="isArray">Phase 4c: when true the node is materialised as a 1-D array
+    /// (<c>ValueRank=OneDimension</c> with <c>ArrayDimensions=[arrayLength]</c>); when false (default) it
+    /// stays scalar (<c>ValueRank=Scalar</c>). Array elements share the scalar's base
+    /// <paramref name="dataType"/> — rank + dimensions carry the array-ness.</param>
+    /// <param name="arrayLength">Phase 4c: the declared length of the 1-D array when
+    /// <paramref name="isArray"/> is true; ignored for scalars. Null ⇒ length 0.</param>
+    public void EnsureVariable(string variableNodeId, string? parentFolderNodeId, string displayName, string dataType, bool writable, string? historianTagname = null, bool isArray = false, uint? arrayLength = null)
     {
         ArgumentException.ThrowIfNullOrEmpty(variableNodeId);
         ArgumentException.ThrowIfNullOrEmpty(displayName);
@@ -1324,7 +1330,8 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2
                 TypeDefinitionId = VariableTypeIds.BaseDataVariableType,
                 ReferenceTypeId = ReferenceTypeIds.Organizes,
                 DataType = ResolveBuiltInDataType(dataType),
-                ValueRank = ValueRanks.Scalar,
+                ValueRank       = isArray ? ValueRanks.OneDimension : ValueRanks.Scalar,
+                ArrayDimensions = isArray ? new ReadOnlyList<uint>(new UInt32Collection(new[] { arrayLength ?? 0u })) : null,
                 AccessLevel = access,
                 UserAccessLevel = access,
                 Historizing = historized,
@@ -2046,7 +2053,11 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2
             TypeDefinitionId = VariableTypeIds.BaseDataVariableType,
             ReferenceTypeId = ReferenceTypeIds.Organizes,
             DataType = DataTypeIds.BaseDataType,
-            ValueRank = ValueRanks.Scalar,
+            // Lazy-created nodes (a WriteValue for a node never declared via EnsureVariable) carry no
+            // array intent, so they stay scalar with no ArrayDimensions — mirrors EnsureVariable's
+            // scalar branch. Array nodes are always pre-declared via EnsureVariable(isArray:true).
+            ValueRank       = ValueRanks.Scalar,
+            ArrayDimensions = null,
             AccessLevel = AccessLevels.CurrentRead,
             UserAccessLevel = AccessLevels.CurrentRead,
             Historizing = false,

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

@@ -60,8 +60,10 @@ public sealed class SdkAddressSpaceSink : IOpcUaAddressSpaceSink
     /// <param name="writable">When true the node is created read/write; otherwise read-only.</param>
     /// <param name="historianTagname">null ⇒ not historized; non-null ⇒ create Historizing with the
     /// HistoryRead access bit and register the historian tagname.</param>
-    public void EnsureVariable(string variableNodeId, string? parentFolderNodeId, string displayName, string dataType, bool writable, string? historianTagname = null)
-        => _nodeManager.EnsureVariable(variableNodeId, parentFolderNodeId, displayName, dataType, writable, historianTagname);
+    /// <param name="isArray">When true the node is created as a 1-D array; when false (default) scalar.</param>
+    /// <param name="arrayLength">The declared length of the 1-D array when <paramref name="isArray"/> is true.</param>
+    public void EnsureVariable(string variableNodeId, string? parentFolderNodeId, string displayName, string dataType, bool writable, string? historianTagname = null, bool isArray = false, uint? arrayLength = null)
+        => _nodeManager.EnsureVariable(variableNodeId, parentFolderNodeId, displayName, dataType, writable, historianTagname, isArray, arrayLength);
 
     /// <summary>Rebuilds the entire OPC UA address space.</summary>
     public void RebuildAddressSpace() => _nodeManager.RebuildAddressSpace();

tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.Tests/DeferredAddressSpaceSinkTests.cs

@@ -115,7 +115,7 @@ public sealed class DeferredAddressSpaceSinkTests
         public void EnsureFolder(string folderNodeId, string? parentNodeId, string displayName)
             => CallQueue.Enqueue($"EF:{folderNodeId}");
         /// <inheritdoc />
-        public void EnsureVariable(string variableNodeId, string? parentFolderNodeId, string displayName, string dataType, bool writable, string? historianTagname = null)
+        public void EnsureVariable(string variableNodeId, string? parentFolderNodeId, string displayName, string dataType, bool writable, string? historianTagname = null, bool isArray = false, uint? arrayLength = null)
         {
             CallQueue.Enqueue($"EV:{variableNodeId}");
             HistorianQueue.Enqueue((variableNodeId, historianTagname));

tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.Tests/NodeManagerArrayTests.cs

@@ -0,0 +1,123 @@
+using Microsoft.Extensions.Logging.Abstractions;
+using Opc.Ua;
+using Shouldly;
+using Xunit;
+using ZB.MOM.WW.OtOpcUa.Commons.OpcUa;
+
+namespace ZB.MOM.WW.OtOpcUa.OpcUaServer.Tests;
+
+/// <summary>
+///     Phase 4c Task 1 — node-manager materialisation honours the array intent. Boot a real
+///     <see cref="OtOpcUaSdkServer"/> through <see cref="OpcUaApplicationHost"/> (the same harness
+///     <see cref="NodeManagerHistorizeTests"/> uses), drive
+///     <see cref="OtOpcUaNodeManager.EnsureVariable"/> with / without the new <c>isArray</c> /
+///     <c>arrayLength</c> params, and assert the created <see cref="BaseDataVariableState"/>'s
+///     <c>ValueRank</c> + <c>ArrayDimensions</c>. Also proves the existing value-write path already
+///     round-trips a CLR array with no change.
+/// </summary>
+public sealed class NodeManagerArrayTests : IDisposable
+{
+    private static CancellationToken Ct => TestContext.Current.CancellationToken;
+
+    private readonly string _pkiRoot = Path.Combine(
+        Path.GetTempPath(),
+        $"otopcua-array-{Guid.NewGuid():N}");
+
+    /// <summary>An array variable is created with ValueRank=OneDimension and a single-element
+    /// ArrayDimensions carrying the requested length.</summary>
+    [Fact]
+    public async Task EnsureVariable_with_isArray_sets_one_dimension_rank_and_array_dimensions()
+    {
+        var (host, server) = await BootAsync();
+        var nm = server.NodeManager!;
+
+        nm.EnsureVariable("eq-1/arr", parentFolderNodeId: null, displayName: "arr", dataType: "Int32",
+            writable: false, historianTagname: null, isArray: true, arrayLength: 8);
+
+        var variable = nm.TryGetVariable("eq-1/arr");
+        variable.ShouldNotBeNull();
+        variable!.ValueRank.ShouldBe(ValueRanks.OneDimension);
+        variable.ArrayDimensions.ShouldNotBeNull();
+        variable.ArrayDimensions.ShouldBe(new uint[] { 8u });
+
+        await host.DisposeAsync();
+    }
+
+    /// <summary>A default (scalar) EnsureVariable call keeps ValueRank=Scalar and leaves
+    /// ArrayDimensions null/empty.</summary>
+    [Fact]
+    public async Task EnsureVariable_default_is_scalar_with_no_array_dimensions()
+    {
+        var (host, server) = await BootAsync();
+        var nm = server.NodeManager!;
+
+        nm.EnsureVariable("eq-1/scalar", parentFolderNodeId: null, displayName: "scalar", dataType: "Int32",
+            writable: false);
+
+        var variable = nm.TryGetVariable("eq-1/scalar");
+        variable.ShouldNotBeNull();
+        variable!.ValueRank.ShouldBe(ValueRanks.Scalar);
+        (variable.ArrayDimensions is null || variable.ArrayDimensions.Count == 0).ShouldBeTrue();
+
+        await host.DisposeAsync();
+    }
+
+    /// <summary>The existing WriteValue path round-trips a CLR array onto an array node with no change:
+    /// after EnsureVariable(isArray:true), WriteValue(int[]) surfaces the array verbatim with Good status.</summary>
+    [Fact]
+    public async Task WriteValue_round_trips_a_clr_array_onto_an_array_node()
+    {
+        var (host, server) = await BootAsync();
+        var nm = server.NodeManager!;
+
+        nm.EnsureVariable("eq-1/arrwrite", parentFolderNodeId: null, displayName: "arrwrite", dataType: "Int32",
+            writable: false, historianTagname: null, isArray: true, arrayLength: 3);
+
+        var payload = new[] { 1, 2, 3 };
+        nm.WriteValue("eq-1/arrwrite", payload, OpcUaQuality.Good, DateTime.UtcNow);
+
+        var variable = nm.TryGetVariable("eq-1/arrwrite");
+        variable.ShouldNotBeNull();
+        variable!.Value.ShouldBe(payload);
+        variable.StatusCode.ShouldBe((StatusCode)StatusCodes.Good);
+
+        await host.DisposeAsync();
+    }
+
+    private async Task<(OpcUaApplicationHost Host, OtOpcUaSdkServer Server)> BootAsync()
+    {
+        var host = new OpcUaApplicationHost(
+            new OpcUaApplicationHostOptions
+            {
+                ApplicationName = "OtOpcUa.ArrayTest",
+                ApplicationUri = $"urn:OtOpcUa.ArrayTest:{Guid.NewGuid():N}",
+                OpcUaPort = AllocateFreePort(),
+                PublicHostname = "localhost",
+                PkiStoreRoot = _pkiRoot,
+            },
+            NullLogger<OpcUaApplicationHost>.Instance);
+
+        var server = new OtOpcUaSdkServer();
+        await host.StartAsync(server, Ct);
+        return (host, server);
+    }
+
+    private static int AllocateFreePort()
+    {
+        using var listener = new System.Net.Sockets.TcpListener(System.Net.IPAddress.Loopback, 0);
+        listener.Start();
+        var port = ((System.Net.IPEndPoint)listener.LocalEndpoint).Port;
+        listener.Stop();
+        return port;
+    }
+
+    /// <summary>Cleans up the PKI root directory.</summary>
+    public void Dispose()
+    {
+        if (Directory.Exists(_pkiRoot))
+        {
+            try { Directory.Delete(_pkiRoot, recursive: true); }
+            catch { /* best-effort cleanup */ }
+        }
+    }
+}

tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.Tests/Phase7ApplierHierarchyTests.cs

@@ -266,7 +266,7 @@ public sealed class Phase7ApplierHierarchyTests : IDisposable
         /// <param name="dataType">The OPC UA built-in type name.</param>
         /// <param name="writable">Whether the node is created read/write.</param>
         /// <param name="historianTagname">The resolved historian tagname (null ⇒ not historized).</param>
-        public void EnsureVariable(string variableNodeId, string? parentFolderNodeId, string displayName, string dataType, bool writable, string? historianTagname = null) { }
+        public void EnsureVariable(string variableNodeId, string? parentFolderNodeId, string displayName, string dataType, bool writable, string? historianTagname = null, bool isArray = false, uint? arrayLength = null) { }
         /// <summary>Rebuilds the address space (stub implementation for testing).</summary>
         public void RebuildAddressSpace() { }
     }

tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.Tests/Phase7ApplierTests.cs

@@ -768,7 +768,7 @@ public sealed class Phase7ApplierTests
         /// <param name="dataType">The OPC UA built-in type name.</param>
         /// <param name="writable">Whether the node is created read/write.</param>
         /// <param name="historianTagname">The resolved historian tagname (null ⇒ not historized).</param>
-        public void EnsureVariable(string variableNodeId, string? parentFolderNodeId, string displayName, string dataType, bool writable, string? historianTagname = null)
+        public void EnsureVariable(string variableNodeId, string? parentFolderNodeId, string displayName, string dataType, bool writable, string? historianTagname = null, bool isArray = false, uint? arrayLength = null)
         {
             VariableQueue.Enqueue((variableNodeId, parentFolderNodeId, displayName, dataType, writable));
             HistorianQueue.Enqueue((variableNodeId, historianTagname));
@@ -818,7 +818,7 @@ public sealed class Phase7ApplierTests
         /// <param name="dataType">The OPC UA built-in type name.</param>
         /// <param name="writable">Whether the node is created read/write.</param>
         /// <param name="historianTagname">The resolved historian tagname (null ⇒ not historized).</param>
-        public void EnsureVariable(string variableNodeId, string? parentFolderNodeId, string displayName, string dataType, bool writable, string? historianTagname = null) { }
+        public void EnsureVariable(string variableNodeId, string? parentFolderNodeId, string displayName, string dataType, bool writable, string? historianTagname = null, bool isArray = false, uint? arrayLength = null) { }
         /// <summary>No-op rebuild address space call.</summary>
         public void RebuildAddressSpace() { }
     }

tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests/Observability/OtOpcUaTelemetryHookTests.cs

@@ -219,7 +219,7 @@ public sealed class OtOpcUaTelemetryHookTests : RuntimeActorTestBase
         /// <param name="dataType">The OPC UA built-in type name.</param>
         /// <param name="writable">Whether the node is created read/write.</param>
         /// <param name="historianTagname">The resolved historian tagname (null ⇒ not historized).</param>
-        public void EnsureVariable(string variableNodeId, string? parentFolderNodeId, string displayName, string dataType, bool writable, string? historianTagname = null) { }
+        public void EnsureVariable(string variableNodeId, string? parentFolderNodeId, string displayName, string dataType, bool writable, string? historianTagname = null, bool isArray = false, uint? arrayLength = null) { }
         /// <summary>Rebuilds address space (recorded via span).</summary>
         public void RebuildAddressSpace() { /* recorded via span */ }
     }

tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests/OpcUa/OpcUaPublishActorRebuildTests.cs

@@ -289,7 +289,7 @@ public sealed class OpcUaPublishActorRebuildTests : RuntimeActorTestBase
         /// <param name="dataType">The OPC UA built-in type name.</param>
         /// <param name="writable">Whether the node is created read/write.</param>
         /// <param name="historianTagname">The resolved historian tagname (null ⇒ not historized).</param>
-        public void EnsureVariable(string variableNodeId, string? parentFolderNodeId, string displayName, string dataType, bool writable, string? historianTagname = null)
+        public void EnsureVariable(string variableNodeId, string? parentFolderNodeId, string displayName, string dataType, bool writable, string? historianTagname = null, bool isArray = false, uint? arrayLength = null)
             => Calls.Enqueue($"EV:{variableNodeId}");
         /// <summary>Records a rebuild address space call.</summary>
         public void RebuildAddressSpace() => Interlocked.Increment(ref RebuildCalls);

tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests/OpcUa/OpcUaPublishActorTests.cs

@@ -592,7 +592,7 @@ public sealed class OpcUaPublishActorTests : RuntimeActorTestBase
         /// <param name="dataType">The OPC UA built-in type name.</param>
         /// <param name="writable">Whether the node is created read/write.</param>
         /// <param name="historianTagname">The resolved historian tagname (null ⇒ not historized).</param>
-        public void EnsureVariable(string variableNodeId, string? parentFolderNodeId, string displayName, string dataType, bool writable, string? historianTagname = null) { }
+        public void EnsureVariable(string variableNodeId, string? parentFolderNodeId, string displayName, string dataType, bool writable, string? historianTagname = null, bool isArray = false, uint? arrayLength = null) { }
 
         /// <summary>Records a rebuild call.</summary>
         public void RebuildAddressSpace() => Interlocked.Increment(ref RebuildCalls);