feat(commons): add IBrowsableDataConnection capability interface

src/ZB.MOM.WW.ScadaBridge.Commons/Interfaces/Protocol/IBrowsableDataConnection.cs

@@ -0,0 +1,48 @@
+namespace ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Protocol;
+
+/// <summary>
+/// Optional capability for an <see cref="IDataConnection"/> implementation
+/// that supports browsing the server's address space. Consumed only by
+/// management/UI flows (e.g. the OPC UA tag picker on the instance config
+/// page) — never by Instance Actors on the hot path.
+/// </summary>
+public interface IBrowsableDataConnection
+{
+    /// <summary>
+    /// Returns the immediate children of <paramref name="parentNodeId"/>, or
+    /// the server's root-level nodes when null.
+    /// </summary>
+    /// <param name="parentNodeId">Node id whose children to browse, or null for the server root (OPC UA ObjectsFolder).</param>
+    /// <param name="cancellationToken">Cancellation token; on cancellation the implementation should throw <see cref="OperationCanceledException"/>.</param>
+    Task<BrowseChildrenResult> BrowseChildrenAsync(
+        string? parentNodeId,
+        CancellationToken cancellationToken = default);
+}
+
+/// <param name="Children">Child nodes returned by the server in browse order.</param>
+/// <param name="Truncated">True when the server reported more children than the per-call cap; remaining children must be discovered via manual entry.</param>
+public record BrowseChildrenResult(
+    IReadOnlyList<BrowseNode> Children,
+    bool Truncated);
+
+/// <param name="NodeId">Server-issued node identifier (e.g. <c>"ns=2;s=Devices.Pump1.Speed"</c>).</param>
+/// <param name="DisplayName">Human-readable display name from the server's DisplayName attribute.</param>
+/// <param name="NodeClass">Classifies the node for UI purposes (Variable rows are selectable; Object rows are navigable).</param>
+/// <param name="HasChildren">Hint so the UI can render an expand chevron without a second roundtrip.</param>
+public record BrowseNode(
+    string NodeId,
+    string DisplayName,
+    BrowseNodeClass NodeClass,
+    bool HasChildren);
+
+public enum BrowseNodeClass { Object, Variable, Method, Other }
+
+/// <summary>
+/// Thrown by <see cref="IBrowsableDataConnection.BrowseChildrenAsync"/> when
+/// the underlying session is not currently connected. Translated to
+/// <c>BrowseFailureKind.ConnectionNotConnected</c> by the site-side handler.
+/// </summary>
+public sealed class ConnectionNotConnectedException : InvalidOperationException
+{
+    public ConnectionNotConnectedException(string message) : base(message) { }
+}