Auto: opcuaclient-9 — method node mirroring + Call passthrough

Adds the 9th capability interface (IMethodInvoker) so the OPC UA Client
driver can mirror upstream OPC UA Method nodes into the local address
space and forward Call invocations as Session.CallAsync. Method-bearing
servers (e.g. ProgramStateMachine, Acknowledge / Confirm methods, custom
control surfaces) now show up downstream instead of being silently
filtered out.

- Core.Abstractions: IMethodInvoker + MethodCallResult; default no-op
  IAddressSpaceBuilder.RegisterMethodNode + MirroredMethodNodeInfo +
  MethodArgumentInfo. Default impls keep tag-based drivers and existing
  builders compiling without forced overrides.
- OpcUaClientDriver: BrowseRecursiveAsync now lifts the Method node-class
  filter; for each method it walks HasProperty to pick up InputArguments
  + OutputArguments and decodes the Argument extension objects into
  MethodArgumentInfo. Status-codes pass through verbatim (cascading
  quality), local NodeId-parse + lost-session faults surface as
  BadNodeIdInvalid / BadCommunicationError.
- 7 new unit tests cover the capability surface, the DTO shapes, and the
  back-compat default no-op for RegisterMethodNode. Suite green at
  160/160.

Server-side OnCallMethod dispatch (wiring local MethodNode handlers to
IMethodInvoker.CallMethodAsync inside DriverNodeManager) is deferred to
a follow-up — the driver-side surface + browse mirror ship cleanly here.

Closes #281

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/ZB.MOM.WW.OtOpcUa.Core.Abstractions/IAddressSpaceBuilder.cs

@@ -60,8 +60,90 @@ public interface IAddressSpaceBuilder
     ///     </para>
     /// </remarks>
     void RegisterTypeNode(MirroredTypeNodeInfo info) { /* default: no-op */ }
+
+    /// <summary>
+    ///     Register a method node mirrored from an upstream OPC UA server. The method is
+    ///     registered as a child of the current builder scope (i.e. the folder representing
+    ///     the upstream Object that owns the method). Optional surface — drivers that don't
+    ///     mirror methods simply never call it; address-space builders that don't materialise
+    ///     method nodes can leave the default no-op in place. Default implementation drops
+    ///     the call so adding this method doesn't break existing
+    ///     <see cref="IAddressSpaceBuilder"/> implementations.
+    /// </summary>
+    /// <param name="info">Metadata describing the method node, including input/output argument schemas.</param>
+    /// <remarks>
+    ///     <para>
+    ///         The OPC UA Client driver is the primary caller — it picks up
+    ///         <c>NodeClass.Method</c> nodes during the <c>HierarchicalReferences</c> browse
+    ///         pass, then walks each method's <c>HasProperty</c> references to harvest the
+    ///         <c>InputArguments</c> / <c>OutputArguments</c> property values.
+    ///     </para>
+    ///     <para>
+    ///         The OPC UA server-side <c>DriverNodeManager</c> overrides this to materialize
+    ///         a real <c>MethodNode</c> in the local address space and wire its
+    ///         <c>OnCallMethod</c> handler to the driver's
+    ///         <see cref="IMethodInvoker.CallMethodAsync"/>. Other builders (Galaxy, Modbus,
+    ///         FOCAS, S7, TwinCAT, AB-CIP, AB-Legacy) ignore the projection because their
+    ///         backends don't expose method nodes.
+    ///     </para>
+    /// </remarks>
+    void RegisterMethodNode(MirroredMethodNodeInfo info) { /* default: no-op */ }
 }
 
+/// <summary>
+///     Metadata describing a single method node mirrored from an upstream OPC UA server.
+///     Built by the OPC UA Client driver during the discovery browse pass and consumed by
+///     <see cref="IAddressSpaceBuilder.RegisterMethodNode"/>.
+/// </summary>
+/// <param name="BrowseName">OPC UA BrowseName segment from the upstream BrowseName.</param>
+/// <param name="DisplayName">Human-readable display name; falls back to <paramref name="BrowseName"/>.</param>
+/// <param name="ObjectNodeId">
+///     Stringified NodeId of the parent Object that owns this method — the <c>ObjectId</c>
+///     argument the dispatcher passes back to <see cref="IMethodInvoker.CallMethodAsync"/>.
+/// </param>
+/// <param name="MethodNodeId">
+///     Stringified NodeId of the method node itself — the <c>MethodId</c> argument.
+/// </param>
+/// <param name="InputArguments">
+///     Declaration of the method's input arguments, in order. <c>null</c> or empty when the
+///     method takes no inputs (or the upstream property couldn't be read).
+/// </param>
+/// <param name="OutputArguments">
+///     Declaration of the method's output arguments, in order. <c>null</c> or empty when the
+///     method returns no outputs (or the upstream property couldn't be read).
+/// </param>
+public sealed record MirroredMethodNodeInfo(
+    string BrowseName,
+    string DisplayName,
+    string ObjectNodeId,
+    string MethodNodeId,
+    IReadOnlyList<MethodArgumentInfo>? InputArguments,
+    IReadOnlyList<MethodArgumentInfo>? OutputArguments);
+
+/// <summary>
+///     One row of an OPC UA Argument array — name + data type + array hint. Mirrors the
+///     <c>Opc.Ua.Argument</c> structure but without the SDK-only types so this DTO can live
+///     in <c>Core.Abstractions</c>.
+/// </summary>
+/// <param name="Name">Argument name from the upstream Argument structure.</param>
+/// <param name="DriverDataType">
+///     Mapped local <see cref="DriverDataType"/>. Unknown / structured upstream types fall
+///     through to <see cref="DriverDataType.String"/> — same convention as variable mirroring.
+/// </param>
+/// <param name="ValueRank">
+///     OPC UA ValueRank: <c>-1</c> = scalar, <c>0</c> = OneOrMoreDimensions, <c>1+</c> = array
+///     dimensions. Driven directly from the upstream Argument's ValueRank.
+/// </param>
+/// <param name="Description">
+///     Human-readable description from the upstream Argument structure; <c>null</c> when the
+///     upstream doesn't carry one.
+/// </param>
+public sealed record MethodArgumentInfo(
+    string Name,
+    DriverDataType DriverDataType,
+    int ValueRank,
+    string? Description);
+
 /// <summary>
 ///     Categorises a mirrored type-definition node so the receiving builder can route it into
 ///     the right OPC UA standard subtree (<c>ObjectTypesFolder</c>, <c>VariableTypesFolder</c>,

src/ZB.MOM.WW.OtOpcUa.Core.Abstractions/IMethodInvoker.cs

@@ -0,0 +1,82 @@
+namespace ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+
+/// <summary>
+///     Driver capability for invoking OPC UA Methods on the upstream backend (the OPC UA
+///     <c>Call</c> service). Optional — only drivers whose backends carry method nodes
+///     implement it. Currently the OPC UA Client driver is the only implementer; tag-based
+///     drivers (Modbus, S7, FOCAS, Galaxy, AB-CIP, AB-Legacy, TwinCAT) don't expose method
+///     nodes so they don't need this surface.
+/// </summary>
+/// <remarks>
+///     <para>
+///         Per <c>docs/v2/plan.md</c> decision #4 (composable capability interfaces) — the
+///         server-side <c>DriverNodeManager</c> discovers method-bearing drivers via an
+///         <c>is IMethodInvoker</c> check and routes <c>OnCallMethod</c> handlers to
+///         <see cref="CallMethodAsync"/>. Drivers that don't implement the interface simply
+///         never have method nodes registered for them.
+///     </para>
+///     <para>
+///         The address-space mirror is driven by <see cref="IAddressSpaceBuilder.RegisterMethodNode"/>
+///         — drivers register the method node + its <c>InputArguments</c> /
+///         <c>OutputArguments</c> properties during discovery, then invocations land back on
+///         <see cref="CallMethodAsync"/> via the server-side dispatcher.
+///     </para>
+/// </remarks>
+public interface IMethodInvoker
+{
+    /// <summary>
+    ///     Invoke an upstream OPC UA Method. The driver translates input arguments into the
+    ///     wire-level <c>CallMethodRequest</c>, dispatches via the active session, and packs
+    ///     the response back into a <see cref="MethodCallResult"/>. Per-argument validation
+    ///     errors flow through <see cref="MethodCallResult.InputArgumentResults"/>; method-level
+    ///     errors (<c>BadMethodInvalid</c>, <c>BadUserAccessDenied</c>, etc.) flow through
+    ///     <see cref="MethodCallResult.StatusCode"/>.
+    /// </summary>
+    /// <param name="objectNodeId">
+    ///     Stringified NodeId of the OPC UA Object that owns the method (the <c>ObjectId</c>
+    ///     field of <c>CallMethodRequest</c>). Same serialization as <c>IReadable</c>'s
+    ///     <c>fullReference</c> — <c>ns=2;s=…</c> / <c>i=…</c> / <c>nsu=…;…</c>.
+    /// </param>
+    /// <param name="methodNodeId">
+    ///     Stringified NodeId of the Method node itself (the <c>MethodId</c> field).
+    /// </param>
+    /// <param name="inputs">
+    ///     Input arguments in declaration order. The driver wraps each value as a
+    ///     <c>Variant</c>; callers pass CLR primitives (plus arrays) — the wire-level
+    ///     encoding is the driver's concern.
+    /// </param>
+    /// <param name="cancellationToken">Per-call cancellation.</param>
+    /// <returns>
+    ///     Result of the call — see <see cref="MethodCallResult"/>. Never throws for a
+    ///     <c>Bad</c> upstream status; the bad code is surfaced via the result so the caller
+    ///     can map it onto an OPC UA service-result for downstream clients.
+    /// </returns>
+    Task<MethodCallResult> CallMethodAsync(
+        string objectNodeId,
+        string methodNodeId,
+        object[] inputs,
+        CancellationToken cancellationToken);
+}
+
+/// <summary>
+///     Result of a single OPC UA <c>Call</c> service invocation.
+/// </summary>
+/// <param name="StatusCode">
+///     Method-level status. <c>0</c> = Good. Bad codes pass through verbatim from the
+///     upstream so downstream clients see the canonical OPC UA error (e.g.
+///     <c>BadMethodInvalid</c>, <c>BadUserAccessDenied</c>, <c>BadArgumentsMissing</c>).
+/// </param>
+/// <param name="Outputs">
+///     Output argument values in declaration order. <c>null</c> when the upstream returned
+///     no output arguments (or returned a Bad status before producing any).
+/// </param>
+/// <param name="InputArgumentResults">
+///     Per-input-argument status codes. <c>null</c> when the upstream didn't surface
+///     per-argument validation results (typical for Good calls). Each entry is the OPC UA
+///     status code for the matching input argument — drivers can use this to surface
+///     <c>BadTypeMismatch</c>, <c>BadOutOfRange</c>, etc. on a specific argument.
+/// </param>
+public sealed record MethodCallResult(
+    uint StatusCode,
+    object[]? Outputs,
+    uint[]? InputArgumentResults);